Download OpenAPI specification:Download
The Metasys REST API is the exposed interface for accessing data from a Johnson
Controls® Metasys system. This spec documents v5 of the API first
released as part of Metasys 13.0. This documentation was last
updated on July 5, 2022, 6:03 PM (UTC).
This version of the documentation includes INTERNAL operations which are only for use by approved Johnson Controls teams/projects.
This version of the documentation includes PRIVATE operations which are only to be used by Metasys developers for Metasys products. These operations should not be shared with other teams within Johnson Controls, nor should they be shared with third parties outside of Johnson Controls.
Metasys is a network-based building automation system (BAS) that operates the mechanical and electrical equipment in your building. For an introduction to Metasys, refer to Metasys System in Metasys System Configuration Guide. For a glossary of Metasys terms, refer to Metasys System Glossary. For additional information on Metasys, search the Johnson Controls documentation site Knowledge Exchange.
This specification defines the operations you can use to retrieve data through the API. For further information on the Metasys API, including tutorials, see the Metasys API home page.
© 2022 Johnson Controls Tyco IP Holdings LLP.
This documentation is for Metasys 13.0 which ships with version 5 of the Metasys Server.
The base path for the API is https://{hostname}/api/v5 where {hostname} is the host name of
your Metasys server.
Multiple versions of this API may be supported on one release of Metasys. At
Metasys 13.0, the supported versions are v2, v3, and
v5.
Note: v1 is not supported by Metasys 13.0.
You must specify which version you intend to use in the URL, using the format
v[#].
For example, https://localhost/api/v5/spaces for version
5 of spaces.
Documentation for v3 and earlier can be found
here.
The Content-Type header of the response will always contain (in part) the
version of the API that was used to serve the request. This allows you to
identify which version of the API was utilized.
For example, Content-Type: application/vnd.metasysapi.v5+json for version
5.
You must obtain an additional license to access some operations. For more information, refer to the Licensing information and Software information sections in Metasys System Software Purchase Options Product Bulletin (LIT-12011703).
The Monitoring and Commanding API enables reading, writing, and commanding one or more Metasys objects/properties, including Present Value. This API succeeds the Metasys System Secure Data Access dynamic link library (MSSDA DLL).
The following operations require the Monitoring and Commanding API license:
In general, you should assume that all URLs, parameter names, parameter values, payload property names and payload property values are case sensitive. For example:
presentValue. It is case sensitive and must always be
spelled presentValue.reliabilityEnumSet.reliable, displayPrecisionEnumSet.displayPrecision1,
and writePriorityEnumSet.priorityDefault).For operations where page and pageSize is allowed, the default page number
will be 1 and is 1-based for all paths while the default pageSize will vary
between paths. The page parameter indicates the page number of items to return
from the path. The pageSize parameter indicates the maximum number of items in
the response from the path.
Payloads returned by pagination-enabled paths have a similar structure. A
total property indicates the total number of items included in all pages. A
next and previous property supplies a link to the next and previous page of
data, respectively. These properties can be empty if irrelevant (for example, if
it is the first/last page, or there is only one page of data). The items
property contains the data included in the page.
For operations where a sort query parameter is allowed, the supplied value
should be in the format of a single attribute name, optionally prefixed with -
to indicate descending sort order (ascending order is used if no prefix is
supplied).
Payloads may contain links to related data, each represented as a property sharing the name of the respective relationship. The links point to either single or multiple related entities. A link to a single entity points to the canonical path for that entity. A link to multiple entities points to a path dedicated to representing that particular relationship.
For example, if object /objects/a has children /objects/b and /objects/c,
the payload returned by /objects/a will have a property objects with a value
of /objects/a/objects, because multiple children can be returned. However, the
payload returned by /objects/b/ will contain a property parent with a value
of /objects/a (not /objects/b/parent), because the relationship represents a
single entity.
Additionally, each payload contain a self property, which contains a link
representing the path used to obtain the data contained in the current payload.
All date-times in the alarms, audits, activities, and samples operations are ISO-8601 encoded strings in UTC. Other operations, such as objects, use a proprietary structure further described in supporting documentation.
There are some general rules that apply across all operations. If certain provided inputs are invalid or preconditions are not met, the API will respond with an appropriate error to indicate what went wrong.
| Condition | Error | Details |
|---|---|---|
| Invalid request body | 400 (Bad Request) | A body is provided which does not adhere to the expected format and/or schema |
| Missing required parameter | 400 (Bad Request) | A parameter marked required in this document is not included in the request |
| Parameter incorrect type | 400 (Bad Request) | A parameter is included with a value of the wrong type (for example, number is expected and string is provided) |
| Parameter out of range | 400 (Bad Request) | A numeric parameter is included but the value is outside the allowed range |
| Parameter not in set | 400 (Bad Request) | A string parameter has a set of predefined valid values, and the value provided is not included in that set |
| Parameter not in correct format | 400 (Bad Request) | A string parameter with expected format is provided in the wrong format |
Unsupported Content-Type |
400 (Bad Request) | An unsupported Content-Type header is provided |
| User not authenticated | 401 (Unauthorized) | The auth token supplied with the request is missing, invalid, or expired |
| Record not authorized | 403 (Forbidden) | The user is not authorized to view data matching the provided identifier or too many requests |
| Invalid user type | 403 (Forbidden) | Not an "API user"; not all user accounts have API access |
| Identifier not found | 404 (Not Found) | An identifier is provided that does not match any known data |
| The resource already exists | 409 (Conflict) | The resource already exists |
| Internal Server Error | 500 (Internal Server Error) | An unexpected error occurred |
| The device is not supported | 501 (Not Implemented) | The server does not support the functionality required to fulfill the request |
| The device is offline | 503 (Service Unavailable) | The device is currently offline and unable to serve the request |
The response payload of some operations in this document have a section of
information labeled schema. This section of information includes important
pieces of metadata about the item or items attributes that gives better
context to the meaning of attribute values. This section follows
JSON Schema specification with added custom
annotation keywords.
Activities are a superset of all alarms and audits in a Metasys system. The activities operations provide the ability to view, annotate, and manage audits and alarms. The use of filters, sorting, and paging allow for the ability to narrow searches to find activities more efficiently.
Clients can subscribe to streaming events for activities. To establish a
subscription, provide a METASYS-SUBSCRIBE header with the
Get Activities operation. The value of this header
is the stream id you received when you opened a stream. The events received on
a subscription are relevant to the filters of the original GET operation.
See also:
The following are types of events sent by an activities subscription along with
example data payloads for each:
activity.alarm.ack - Indicates a management status change of an alarm
activity to acknowledged.
{
"subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
"activity": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
"objectName": "OA_T",
"activityManagementStatus": "acknowledged",
"creationTime": "2021-02-16T20:30:00Z",
"spaces": [
{
"id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
"itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
"name": "Floor 1",
"spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"equipment": [
{
"id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
"itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
"equipmentName": "Engine1",
"shortName": null,
"equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
"objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
"alarm": {
"message": "",
"alarmGeneratorObject": {
"objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
"referencedObject": {
"objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
}
},
"isAckRequired": true,
"acknowledgedTime": "2021-02-16T20:31:02Z",
"type": "alarmValueEnumSet.avHiAlarm",
"priority": 70,
"category": "objectCategoryEnumSet.generalCategory",
"annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
"self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
"triggerValue": {
"item": "2.0",
"schema": {
"type": "string",
"metasysType": "string",
"units": {
"id": "unitEnumSet.degF",
"title": "deg F"
}
}
},
"description": ""
}
},
"effectivePermission": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"canAcknowledge": true,
"canDiscard": true,
"canAnnotate": true
}
}
activity.alarm.annotate - Indicates the addition of an annotation to an
alarm activity, providing the information for the annotated alarm.
{
"subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
"activity": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
"objectName": "OA_T",
"activityManagementStatus": "pending",
"creationTime": "2021-02-16T20:30:00Z",
"spaces": [
{
"id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
"itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
"name": "Floor 1",
"spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"equipment": [
{
"id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
"itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
"equipmentName": "Engine1",
"shortName": null,
"equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
"objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
"alarm": {
"message": "",
"alarmGeneratorObject": {
"objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
"referencedObject": {
"objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
}
},
"isAckRequired": true,
"acknowledgedTime": "2021-02-16T20:31:02Z",
"type": "alarmValueEnumSet.avHiAlarm",
"priority": 70,
"category": "objectCategoryEnumSet.generalCategory",
"annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
"self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
"triggerValue": {
"item": "2.0",
"schema": {
"type": "string",
"metasysType": "string",
"units": {
"id": "unitEnumSet.degF",
"title": "deg F"
}
}
},
"description": ""
}
},
"effectivePermission": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"canAcknowledge": true,
"canDiscard": true,
"canAnnotate": true
}
}
activity.alarm.discard - Indicates a management status change of an alarm
activity to discarded.
{
"subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
"activity": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
"objectName": "OA_T",
"activityManagementStatus": "discarded",
"creationTime": "2021-02-16T20:30:00Z",
"spaces": [
{
"id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
"itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
"name": "Floor 1",
"spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"equipment": [
{
"id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
"itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
"equipmentName": "Engine1",
"shortName": null,
"equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
"objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
"alarm": {
"message": "",
"alarmGeneratorObject": {
"objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
"referencedObject": {
"objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
}
},
"isAckRequired": true,
"acknowledgedTime": "2021-02-16T20:31:02Z",
"type": "alarmValueEnumSet.avHiAlarm",
"priority": 70,
"category": "objectCategoryEnumSet.generalCategory",
"annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
"self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
"triggerValue": {
"item": "2.0",
"schema": {
"type": "string",
"metasysType": "string",
"units": {
"id": "unitEnumSet.degF",
"title": "deg F"
}
}
},
"description": ""
}
},
"effectivePermission": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"canAcknowledge": true,
"canDiscard": true,
"canAnnotate": true
}
}
activity.alarm.new - Indicates the creation of an alarm activity.
{
"subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
"activity": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
"objectName": "OA_T",
"activityManagementStatus": "pending",
"creationTime": "2021-02-16T20:30:00Z",
"spaces": [
{
"id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
"itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
"name": "Floor 1",
"spaceUrl": "https://{hostname}/api/v5/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"equipment": [
{
"id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
"itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
"equipmentName": "IDU1",
"shortName": null,
"equipmentUrl": "https://{hostname}/api/v5/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
}
],
"objectUrl": "https://{hostname}/api/v5/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
"objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
"alarm": {
"message": "",
"alarmGeneratorObject": {
"objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
"referencedObject": {
"objectUrl": "https://{hostname}/api/v5/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
}
},
"isAckRequired": true,
"type": "alarmValueEnumSet.avHiAlarm",
"priority": 70,
"category": "objectCategoryEnumSet.generalCategory",
"annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
"self": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
"triggerValue": {
"item": "2.0",
"schema": {
"type": "string",
"metasysType": "string",
"units": {
"id": "unitEnumSet.degF",
"title": "deg F"
}
}
},
"description": ""
}
},
"effectivePermission": {
"id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
"canAcknowledge": true,
"canDiscard": true,
"canAnnotate": true
}
}
activity.audit.new - Indicates the creation of an audit activity.
{
"subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
"activity": {
"id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
"itemReference": "{hostname}:{deviceHostname}",
"objectName": "MS-NAE5510-3",
"activityManagementStatus": "pending",
"creationTime": "2021-02-16T16:21:10.23Z",
"objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
"objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
"audit": {
"actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
"status": null,
"preData": null,
"postData": {
"item": "10.10.198.131",
"schema": {
"type": "string",
"metasysType": "string"
}
},
"parameters": [],
"errorString": null,
"user": "MetasysSysAgent",
"signature": null,
"classLevel": "auditClassesEnumSet.userActionAuditClass",
"originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
"description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
"annotationsUrl": null,
"self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
}
},
"effectivePermission": {
"id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
"canDiscard": true
}
}
activity.audit.annotate - Indicates the addition of an annotation to an
audit activity, providing the information for the annotated audit.
{
"subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
"activity": {
"id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
"itemReference": "{hostname}:{deviceHostname}",
"objectName": "MS-NAE5510-3",
"activityManagementStatus": "pending",
"creationTime": "2021-02-16T16:21:10.23Z",
"objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
"objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
"audit": {
"actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
"status": null,
"preData": null,
"postData": {
"item": "10.10.198.131",
"schema": {
"type": "string",
"metasysType": "string"
}
},
"parameters": [],
"errorString": null,
"user": "MetasysSysAgent",
"signature": null,
"classLevel": "auditClassesEnumSet.userActionAuditClass",
"originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
"description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
"annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
"self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
}
},
"effectivePermission": {
"id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
"canDiscard": true
}
}
activity.audit.discard - Indicates a management status change of an audit
activity to discarded.
{
"subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
"activity": {
"id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
"itemReference": "{hostname}:{deviceHostname}",
"objectName": "MS-NAE5510-3",
"activityManagementStatus": "discarded",
"creationTime": "2021-02-16T16:21:10.23Z",
"objectUrl": "https://{hostname}/api/v5/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
"objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
"audit": {
"actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
"status": null,
"preData": null,
"postData": {
"item": "10.10.198.131",
"schema": {
"type": "string",
"metasysType": "string"
}
},
"parameters": [],
"errorString": null,
"user": "MetasysSysAgent",
"signature": null,
"classLevel": "auditClassesEnumSet.userActionAuditClass",
"originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
"description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
"annotationsUrl": "https://{hostname}/api/v5/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
"self": "https://{hostname}/api/v5/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
}
},
"effectivePermission": {
"id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
"canDiscard": true
}
}
activity.heartbeat - Indicates the activities service is alive.
{
"currentTime": "2021-02-16T16:21:10.23Z",
"subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"]
}
Filters supplied to an activities request will limit the results to activities
for which they apply. When subscribing to an activities request that uses
filters, the events received are also limited to the same filter criteria.
Exceptions to this behavior occur when filtering on activity management status,
such as for acknowledged or discarded activities. You receive an update
whenever an activity management change occurs, regardless of filters, because
the change may impact the original set of activities you subscribed to. To
illustrate, consider the following scenario:
acknowledged activities and receive all acknowledged
activities, receiving updates for any acknowledged thereafter across the
stream.discarded by
another user.When this occurs, you will receive an activity.alarm.discard message for the
discarded activity even though your filters exclude activities that are
discarded. This is necessary so that you can properly maintain the state of
activities already received in your application.
Retrieves a collection of activities.
| activityType | Array of strings[ items <= 2 items ] Items Enum: "alarm" "audit" Example: activityType=alarm Limit the activities returned to a specific type |
| includeDiscarded | boolean Determines whether discarded activities will be included in the results or
be the only type of activity in the results. Discarded activities are those
for which the This parameter can produce 3 different types of results.
|
| continuationToken | string Example: continuationToken=eyJhdWRpdCI6eyJpZCI6IjgOTQ2NjUzLTlmM... Provide a token from a previous request to fetch the next set of results. Ignored for streaming subscriptions. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" "priority" "-priority" Example: sort=creationTime The criteria to use when sorting results (see rules). |
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| equipment | Array of strings <= 100 items Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398 Filter by list of equipment identifiers. |
| object | Array of strings <= 100 items Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7 Filter by list of object identifiers. |
| space | Array of strings <= 100 items Example: space=214f52d1-0c56-4a29-a690-abe5656d1647 Filter by list of space identifiers. |
| priorityRange | string^\d+,\d+$ Example: priorityRange=0,255 Includes only results within the specified alarm priority range, from 0 to 255 inclusive. |
| type | Array of strings[ items <= 100 items ] Example: type=alarmValueEnumSet.avHighLimit metasysEnum: alarmValueEnumSet Limits the alarms returned to specified types. The acceptable values for the elements of this parameter come from the See also:
|
| includeAcknowledged | boolean Determines whether acknowledged alarms will be included in the results or be
the only type of alarm in the results. Acknowledged alarms are those which
have an This parameter can produce 3 different types of results.
|
| includeAcknowledgementRequired | boolean Default: true Example: includeAcknowledgementRequired=true Determines whether activities which can be acknowledged are included in the
results. When the value is The use of this parameter implies a filter of |
| includeAcknowledgementNotRequired | boolean Default: true Example: includeAcknowledgementNotRequired=true Determines whether activities which can not be acknowledged are included in
the results. When the value is The use of this parameter implies a filter of |
| category | Array of strings Example: category=objectCategoryEnumSet.hvacCategory metasysEnum: objectCategoryEnumSet The authorization category of the requested activities. The acceptable values for the elements of this parameter come from the See also:
|
| originApplication | Array of strings Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp metasysEnum: auditOriginAppEnumSet Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message. The acceptable values for the elements of this parameter come from the See also:
|
| classLevel | Array of strings Example: classLevel=auditClassesEnumSet.userActionAuditClass metasysEnum: auditClassesEnumSet Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose. The Enabled Audit Level attribute ( The acceptable values for the elements of this parameter come from the See also:
|
| actionType | Array of strings Example: actionType=auditActionTypeEnumSet.writeAuditActionType metasysEnum: auditActionTypeEnumSet Filter by list of action types. The action type property indicates the user or system action performed. The acceptable values for the elements of this parameter come from the See also:
|
| user | Array of strings <= 100 items Example: user=metasysuser Filter by list of users. The user property indicates which user initiated the action being audited. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/activities?activityType=alarm&includeDiscarded=false&continuationToken=eyJhdWRpdCI6eyJpZCI6IjgOTQ2NjUzLTlmM...&sort=creationTime&startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&category=objectCategoryEnumSet.hvacCategory&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
The first 10 activities.
{- "total": 4096,
- "items": [
- {
- "id": "648070d6-3b00-4027-ad07-63e9247f4e40",
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Site Director",
- "activityManagementStatus": "pending",
- "creationTime": "2022-01-06T15:16:33.403Z",
- "objectId": "c05d5d30-ebf0-5533-8e67-f74bb728bf18",
- "audit": {
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "jane-doe",
- "signature": null,
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
- "annotationsUrl": null,
}
}, - {
- "id": "bf350492-bf03-43d5-8c50-6d9727e420fe",
- "itemReference": "{hostname}:{deviceHostname}/AV1",
- "objectName": "AV1",
- "activityManagementStatus": "pending",
- "creationTime": "2022-01-06T15:16:18Z",
- "equipment": [
- {
- "id": "ef24e09e-fc26-5113-b91e-607dd6f81b93",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine 1",
- "equipmentName": "My Engine 1",
- "shortName": "My Engine 1.AV1",
}
], - "objectId": "559081e4-4ddd-5923-ab03-85c1797126a5",
- "alarm": {
- "message": "",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV1.Alarm1",
- "referencedObject": {
}
}, - "isAckRequired": true,
- "type": "alarmValueEnumSet.avHiAlarm",
- "priority": 100,
- "category": "objectCategoryEnumSet.generalCategory",
- "annotationsUrl": null,
- "triggerValue": {
- "item": "82.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.degF",
- "title": "deg F"
}
}
}, - "description": "Zone Temperature"
}
}, - {
- "id": "489e0aa2-2185-4e6f-b761-d6d34c0d2250",
- "itemReference": "BV1",
- "objectName": "BV1",
- "activityManagementStatus": "pending",
- "creationTime": "2022-01-06T15:15:47Z",
- "equipment": [
- {
- "id": "22ac4434-f281-56fc-8faa-17bc5456d817",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine 2",
- "equipmentName": "My Engine 2",
- "shortName": "My Engine 2.BV1",
}
], - "objectId": "c5154374-94e9-5f0e-810e-cde0ec69e5a3",
- "alarm": {
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "category": "objectCategoryEnumSet.generalCategory",
- "annotationsUrl": null,
- "triggerValue": {
- "item": "falsetrueEnumSet.falsetrueFalse",
- "schema": {
- "type": "string",
- "metasysType": "enum",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "description": "Generator Boolean Output"
}
}, - {
- "id": "623e3843-3bc8-4db8-96d7-a0c838ef669f",
- "itemReference": "{hostname}:{deviceHostname}/BV2",
- "objectName": "BV2",
- "activityManagementStatus": "pending",
- "creationTime": "2022-01-06T15:15:39Z",
- "equipment": [
- {
- "id": "73939449-fbcc-5548-a3ef-7e827803bc88",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine 3",
- "equipmentName": "My Engine 3",
- "shortName": "My Engine 3.BV2",
}
], - "objectId": "2af82590-b945-59a1-b864-fcff3502e705",
- "alarm": {
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "category": "objectCategoryEnumSet.generalCategory",
- "annotationsUrl": null,
- "triggerValue": {
- "item": "falsetrueEnumSet.falsetrueFalse",
- "schema": {
- "type": "string",
- "metasysType": "enum",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "description": "Generator Boolean Output"
}
}, - {
- "id": "524fa397-488c-4dde-84a9-5434a4e8db86",
- "itemReference": "{hostname}:{deviceHostname}/BV3",
- "objectName": "BV3",
- "activityManagementStatus": "pending",
- "creationTime": "2022-01-06T15:15:24Z",
- "objectId": "6c099bab-7078-5b77-b11b-c4e9c07b3325",
- "alarm": {
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "category": "objectCategoryEnumSet.generalCategory",
- "annotationsUrl": null,
- "triggerValue": {
- "item": "falsetrueEnumSet.falsetrueFalse",
- "schema": {
- "type": "string",
- "metasysType": "enum",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "description": "Generator Boolean Output"
}
}, - {
- "id": "f3a93177-034b-4783-82b2-75603e4738ec",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "objectName": "AV2",
- "activityManagementStatus": "pending",
- "creationTime": "2022-01-06T15:15:21Z",
- "equipment": [
- {
- "id": "7a3b3e13-cf3c-545f-8257-b52e25febe5d",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine 4",
- "equipmentName": "My Engine 4",
- "shortName": "My Engine 4.AV2",
}
], - "objectId": "82810278-0a25-5fa5-be22-709576e00436",
- "alarm": {
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "category": "objectCategoryEnumSet.generalCategory",
- "annotationsUrl": null,
- "triggerValue": {
- "item": "77.9",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.degF",
- "title": "deg F"
}
}
}, - "description": "Zone Temperature"
}
}, - {
- "id": "6ebe04bb-8b14-4abf-8a4c-272cd74d186e",
- "itemReference": "{hostname}:{deviceHostname}/AV3",
- "objectName": "AV3",
- "activityManagementStatus": "pending",
- "creationTime": "2022-01-06T15:15:09Z",
- "equipment": [
- {
- "id": "4d849b49-3bea-50f9-b5c9-049fddcdf57f",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine 5",
- "equipmentName": "My Engine 5",
- "shortName": "My Engine 5.AV3",
}
], - "objectId": "562e2372-15f1-5fcf-a8a4-1868bc369857",
- "alarm": {
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "category": "objectCategoryEnumSet.generalCategory",
- "annotationsUrl": null,
- "triggerValue": {
- "item": "77.9",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.degF",
- "title": "deg F"
}
}
}, - "description": "Zone Temperature"
}
}, - {
- "id": "a025f912-1855-4a85-9056-78cf466fe7d9",
- "itemReference": "{hostname}:{deviceHostname}/AV4",
- "objectName": "AV4",
- "activityManagementStatus": "pending",
- "creationTime": "2022-01-06T15:14:15Z",
- "equipment": [
- {
- "id": "21bd393a-d32f-5480-86db-c6887067eaaa",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine 6",
- "equipmentName": "My Engine 6",
- "shortName": "My Engine 6.AV4",
}
], - "objectId": "9f136e48-2076-5130-94e8-62c3879cee5e",
- "alarm": {
- "message": "",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV4.Alarm1",
- "referencedObject": {
}
}, - "isAckRequired": true,
- "type": "alarmValueEnumSet.avHiAlarm",
- "priority": 50,
- "category": "objectCategoryEnumSet.generalCategory",
- "annotationsUrl": null,
- "triggerValue": {
- "item": "82.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.degF",
- "title": "deg F"
}
}
}, - "description": "Zone Temperature"
}
}, - {
- "id": "8537c846-fb2e-4d9e-b93e-61e56d9bf313",
- "itemReference": "{hostname}:{deviceHostname}/AV5",
- "objectName": "AV5",
- "activityManagementStatus": "pending",
- "creationTime": "2022-01-06T15:14:15Z",
- "equipment": [
- {
- "id": "278e9997-e2e3-5e02-b6f6-45202c6f79b0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine 7",
- "equipmentName": "My Engine 7",
- "shortName": "My Engine 7.AV5",
}
], - "objectId": "3fe4a15e-c42d-5629-b112-6b3ad48e968c",
- "alarm": {
- "message": "",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV5.Alarm1",
- "referencedObject": {
}
}, - "isAckRequired": true,
- "type": "alarmValueEnumSet.avHiAlarm",
- "priority": 100,
- "category": "objectCategoryEnumSet.generalCategory",
- "annotationsUrl": null,
- "triggerValue": {
- "item": "82.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.degF",
- "title": "deg F"
}
}
}, - "description": "Zone Temperature"
}
}, - {
- "id": "7155c042-a23d-4344-a8fc-72c5c6c3875d",
- "itemReference": "{hostname}:{deviceHostname}/BV4",
- "objectName": "BV4",
- "activityManagementStatus": "pending",
- "creationTime": "2022-01-06T15:14:09Z",
- "objectId": "5a056b2f-fcf3-57b8-b473-ee455947f45f",
- "alarm": {
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "category": "objectCategoryEnumSet.generalCategory",
- "annotationsUrl": null,
- "triggerValue": {
- "item": "falsetrueEnumSet.falsetrueFalse",
- "schema": {
- "type": "string",
- "metasysType": "enum",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "description": "Generator Boolean Output"
}
}
], - "effectivePermissions": [
- {
- "id": "648070d6-3b00-4027-ad07-63e9247f4e40",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "bf350492-bf03-43d5-8c50-6d9727e420fe",
- "canAcknowledge": true,
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "489e0aa2-2185-4e6f-b761-d6d34c0d2250",
- "canAcknowledge": true,
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "623e3843-3bc8-4db8-96d7-a0c838ef669f",
- "canAcknowledge": true,
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "524fa397-488c-4dde-84a9-5434a4e8db86",
- "canAcknowledge": true,
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "f3a93177-034b-4783-82b2-75603e4738ec",
- "canAcknowledge": true,
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "6ebe04bb-8b14-4abf-8a4c-272cd74d186e",
- "canAcknowledge": true,
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "a025f912-1855-4a85-9056-78cf466fe7d9",
- "canAcknowledge": true,
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "8537c846-fb2e-4d9e-b93e-61e56d9bf313",
- "canAcknowledge": true,
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "7155c042-a23d-4344-a8fc-72c5c6c3875d",
- "canAcknowledge": true,
- "canDiscard": true,
- "canAnnotate": true
}
],
}This operation is used to invoke multiple activity operations in a single HTTP request. In this version of the API, the only activity related operations that can be used in a batch are listed below.
See also
| method required | string Enum: "PATCH" "POST" The HTTP method to use for each request. |
required | Array of objects A collection of entries that represent the operations to invoke. |
A request to discard multiple activities (2 audits and 2 alarms). One audit request and one alarm request include annotation text and the other requests do not.
{- "method": "PATCH",
- "requests": [
- {
- "id": "1",
- "body": {
- "activityManagementStatus": "discarded",
- "annotationText": "Issue resolved"
}
}, - {
- "id": "2",
- "body": {
- "activityManagementStatus": "discarded"
}
}, - {
- "id": "3",
- "body": {
- "activityManagementStatus": "discarded",
- "annotationText": "Issue resolved"
}
}, - {
- "id": "4",
- "body": {
- "activityManagementStatus": "discarded"
}
}
]
}This is an example response to a batch request. Two of the operations succeeded and two of them failed.
{- "responses": [
- {
- "responseId": "1",
- "status": 204
}, - {
- "responseId": "2",
- "status": 400
}, - {
- "responseId": "3",
- "status": 204
}, - {
- "responseId": "4",
- "status": 400
}
]
}Deletes a subscription to the activities resource.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
curl --request DELETE \ --url https:///%7Bhostname%7D/api/v5/activities/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Alarms alert users to potential problems identified by a Metasys system, for example high zone temperatures. Use alarms operations to get object alarms, network device alarms, single alarms, alarm collections, and alarm annotations. Acknowledge or discard alarms with the edit patch operation. Filter the results with the query parameters time, priority, type, category, acknowledgement, and page. Sort the results by creation time and priority.
Retrieves a collection of alarms for the specified object.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| priorityRange | string^\d+,\d+$ Example: priorityRange=0,255 Includes only results within the specified alarm priority range, from 0 to 255 inclusive. |
| type | Array of strings[ items <= 100 items ] Example: type=alarmValueEnumSet.avHighLimit metasysEnum: alarmValueEnumSet Limits the alarms returned to specified types. The acceptable values for the elements of this parameter come from the See also:
|
| includeAcknowledged | boolean Determines whether acknowledged alarms will be included in the results or be
the only type of alarm in the results. Acknowledged alarms are those which
have an This parameter can produce 3 different types of results.
|
| includeDiscarded | boolean Determines whether discarded alarms will be included in the results or be
the only type of alarm in the results. Discarded alarms are those for which
the
|
| includeAcknowledgementRequired | boolean Default: true Example: includeAcknowledgementRequired=true Determines whether alarms which can be acknowledged are included in the results. When the value is |
| includeAcknowledgementNotRequired | boolean Default: true Example: includeAcknowledgementNotRequired=true Determines whether alarms which can not be acknowledged are included in the results. When the value is |
| category | Array of strings Example: category=objectCategoryEnumSet.hvacCategory metasysEnum: objectCategoryEnumSet The authorization category of the requested activities. The acceptable values for the elements of this parameter come from the See also:
|
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" "priority" "-priority" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The first 10 alarms.
{- "total": 403,
- "previous": null,
- "items": [
- {
- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T17:00:07Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "999235c5-9f4a-42f9-8ea5-863cc6a08eed",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV2.Alarm1",
- "referencedObject": {
}
}, - "message": "",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avLoAlarm",
- "priority": 70,
- "triggerValue": {
- "item": "0.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T05:00:00Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "6e1d7f3b-226b-4b36-811f-849d8e32810d",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T16:59:52Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "991cfa4b-e1c2-4e79-b309-903acebc8a65",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV2.Alarm1",
- "referencedObject": {
}
}, - "message": "",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avLoAlarm",
- "priority": 70,
- "triggerValue": {
- "item": "0.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T05:00:00Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "78271a1f-5985-441e-9893-4c887259d9c6",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-30T17:00:00Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "f281f4aa-56d3-4e5d-bf23-c4e61e439c08",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV2.Alarm1",
- "referencedObject": {
}
}, - "message": "",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avLoAlarm",
- "priority": 70,
- "triggerValue": {
- "item": "0.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-30T05:00:00Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "41621c0a-a369-44d1-8b41-ef0ac2b3977a",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-29T16:59:59Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "ed778832-f47a-436f-8fde-fd38f7af73bc",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV2.Alarm1",
- "referencedObject": {
}
}, - "message": "",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avLoAlarm",
- "priority": 70,
- "triggerValue": {
- "item": "0.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-29T05:00:00Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "54a7fda0-87f4-4ce1-a2de-b19a25186dee",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-28T16:59:59Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "df0f6135-359c-4d69-9645-36fa2a5a2c13",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV2.Alarm1",
- "referencedObject": {
}
}, - "discardedTime": "2021-08-28T21:32:42.247Z",
- "message": "",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avLoAlarm",
- "priority": 70,
- "triggerValue": {
- "item": "0.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-28T05:00:00Z",
- "activityManagementStatus": "discarded",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}
], - "effectivePermissions": [
- {
- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "999235c5-9f4a-42f9-8ea5-863cc6a08eed",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "6e1d7f3b-226b-4b36-811f-849d8e32810d",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "991cfa4b-e1c2-4e79-b309-903acebc8a65",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "78271a1f-5985-441e-9893-4c887259d9c6",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "f281f4aa-56d3-4e5d-bf23-c4e61e439c08",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "41621c0a-a369-44d1-8b41-ef0ac2b3977a",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "ed778832-f47a-436f-8fde-fd38f7af73bc",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "54a7fda0-87f4-4ce1-a2de-b19a25186dee",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "df0f6135-359c-4d69-9645-36fa2a5a2c13",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}
],
}Retrieves a collection of alarms for the specified network device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| priorityRange | string^\d+,\d+$ Example: priorityRange=0,255 Includes only results within the specified alarm priority range, from 0 to 255 inclusive. |
| type | Array of strings[ items <= 100 items ] Example: type=alarmValueEnumSet.avHighLimit metasysEnum: alarmValueEnumSet Limits the alarms returned to specified types. The acceptable values for the elements of this parameter come from the See also:
|
| includeAcknowledged | boolean Determines whether acknowledged alarms will be included in the results or be
the only type of alarm in the results. Acknowledged alarms are those which
have an This parameter can produce 3 different types of results.
|
| includeDiscarded | boolean Determines whether discarded alarms will be included in the results or be
the only type of alarm in the results. Discarded alarms are those for which
the
|
| includeAcknowledgementRequired | boolean Default: true Example: includeAcknowledgementRequired=true Determines whether alarms which can be acknowledged are included in the results. When the value is |
| includeAcknowledgementNotRequired | boolean Default: true Example: includeAcknowledgementNotRequired=true Determines whether alarms which can not be acknowledged are included in the results. When the value is |
| equipment | Array of strings <= 100 items Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398 Filter by list of equipment identifiers. |
| object | Array of strings <= 100 items Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7 Filter by list of object identifiers. |
| space | Array of strings <= 100 items Example: space=214f52d1-0c56-4a29-a690-abe5656d1647 Filter by list of space identifiers. |
| category | Array of strings Example: category=objectCategoryEnumSet.hvacCategory metasysEnum: objectCategoryEnumSet The authorization category of the requested activities. The acceptable values for the elements of this parameter come from the See also:
|
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" "priority" "-priority" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The first 10 alarms.
{- "total": 9027,
- "previous": null,
- "items": [
- {
- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T17:00:07Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "cbc0a848-9231-4608-b958-276d3f2e9f3e",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "",
- "name": "My Engine",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "jciSystemStatusEnumSet.jciOperational",
- "schema": {
- "type": "string",
- "metasysType": "enum",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T05:02:03Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null
}, - {
- "id": "673c8b44-8667-4216-8856-e0d6c41aea6c",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "",
- "name": "My Engine",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/Alarm - JCI System Status",
- "referencedObject": {
}
}, - "message": "",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avAlarm",
- "priority": 70,
- "triggerValue": {
- "item": "jciSystemStatusEnumSet.onboardUploadInProgress",
- "schema": {
- "type": "string",
- "metasysType": "enum",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T05:02:00Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null
}, - {
- "id": "999235c5-9f4a-42f9-8ea5-863cc6a08eed",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV2.Alarm1",
- "referencedObject": {
}
}, - "message": "",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avLoAlarm",
- "priority": 70,
- "triggerValue": {
- "item": "0.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T05:00:00Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "6e1d7f3b-226b-4b36-811f-849d8e32810d",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T16:59:52Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "f58f0068-f84a-4648-8ae7-bdf66c60994f",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "",
- "name": "My Engine",
- "message": "{hostname}:{deviceHostname} is online",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avOnline",
- "priority": 106,
- "triggerValue": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T13:19:35Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null
}, - {
- "id": "243e039d-0cf0-4efb-a88f-5ff342d45c95",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "",
- "name": "My Engine",
- "message": "{hostname}:{deviceHostname} is offline",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avOffline",
- "priority": 106,
- "triggerValue": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T13:19:25Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null
}, - {
- "id": "dfc444d7-1a6c-4ae2-9347-8d8acf7f349a",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "",
- "name": "My Site Director",
- "message": "{hostname}:{deviceHostname} is online",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avOnline",
- "priority": 106,
- "triggerValue": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T13:19:24Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null
}, - {
- "id": "ddf30e8e-ff6e-4036-b067-6e2617fa8244",
- "itemReference": "{hostname}:{deviceHostname}/AV3",
- "description": "",
- "name": "AV3",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV3.Alarm1",
- "referencedObject": {
}
}, - "message": "",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avUnreliable",
- "priority": 70,
- "triggerValue": {
- "item": "2.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T13:19:22Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.generalCategory",
- "annotationsUrl": null
}, - {
- "id": "5b9a300d-d953-4e8f-902f-84da1c3d0deb",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "Dormant User Account",
- "name": "User Account I18NUser on device My Site Director",
- "message": "User Account has been unused or has not successfully logged in since 45 day(s)",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avAlarm",
- "priority": 220,
- "triggerValue": {
- "item": "66",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T12:53:53.977Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null
}
], - "effectivePermissions": [
- {
- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "cbc0a848-9231-4608-b958-276d3f2e9f3e",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "673c8b44-8667-4216-8856-e0d6c41aea6c",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "999235c5-9f4a-42f9-8ea5-863cc6a08eed",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "6e1d7f3b-226b-4b36-811f-849d8e32810d",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "f58f0068-f84a-4648-8ae7-bdf66c60994f",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "243e039d-0cf0-4efb-a88f-5ff342d45c95",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "dfc444d7-1a6c-4ae2-9347-8d8acf7f349a",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "ddf30e8e-ff6e-4036-b067-6e2617fa8244",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "5b9a300d-d953-4e8f-902f-84da1c3d0deb",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}
], - "networkDeviceUrl": "https://{hostname}/api/v5/networkDevices/088333f5-f76e-5177-85aa-73aa32f1c8b3",
}Retrieves a collection of alarms.
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| priorityRange | string^\d+,\d+$ Example: priorityRange=0,255 Includes only results within the specified alarm priority range, from 0 to 255 inclusive. |
| type | Array of strings[ items <= 100 items ] Example: type=alarmValueEnumSet.avHighLimit metasysEnum: alarmValueEnumSet Limits the alarms returned to specified types. The acceptable values for the elements of this parameter come from the See also:
|
| includeAcknowledged | boolean Determines whether acknowledged alarms will be included in the results or be
the only type of alarm in the results. Acknowledged alarms are those which
have an This parameter can produce 3 different types of results.
|
| includeDiscarded | boolean Determines whether discarded alarms will be included in the results or be
the only type of alarm in the results. Discarded alarms are those for which
the
|
| includeAcknowledgementRequired | boolean Default: true Example: includeAcknowledgementRequired=true Determines whether alarms which can be acknowledged are included in the results. When the value is |
| includeAcknowledgementNotRequired | boolean Default: true Example: includeAcknowledgementNotRequired=true Determines whether alarms which can not be acknowledged are included in the results. When the value is |
| equipment | Array of strings <= 100 items Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398 Filter by list of equipment identifiers. |
| object | Array of strings <= 100 items Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7 Filter by list of object identifiers. |
| space | Array of strings <= 100 items Example: space=214f52d1-0c56-4a29-a690-abe5656d1647 Filter by list of space identifiers. |
| category | Array of strings Example: category=objectCategoryEnumSet.hvacCategory metasysEnum: objectCategoryEnumSet The authorization category of the requested activities. The acceptable values for the elements of this parameter come from the See also:
|
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" "priority" "-priority" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The first 10 alarms.
{- "total": 10154,
- "previous": null,
- "items": [
- {
- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T17:00:07Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "cbc0a848-9231-4608-b958-276d3f2e9f3e",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "",
- "name": "My Engine",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "jciSystemStatusEnumSet.jciOperational",
- "schema": {
- "type": "string",
- "metasysType": "enum",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T05:02:03Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null
}, - {
- "id": "673c8b44-8667-4216-8856-e0d6c41aea6c",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "",
- "name": "My Engine",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/Alarm - JCI System Status",
- "referencedObject": {
}
}, - "message": "",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avAlarm",
- "priority": 70,
- "triggerValue": {
- "item": "jciSystemStatusEnumSet.onboardUploadInProgress",
- "schema": {
- "type": "string",
- "metasysType": "enum",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T05:02:00Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null
}, - {
- "id": "999235c5-9f4a-42f9-8ea5-863cc6a08eed",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV2.Alarm1",
- "referencedObject": {
}
}, - "message": "",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avLoAlarm",
- "priority": 70,
- "triggerValue": {
- "item": "0.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T05:00:00Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "6e1d7f3b-226b-4b36-811f-849d8e32810d",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T16:59:52Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}, - {
- "id": "f58f0068-f84a-4648-8ae7-bdf66c60994f",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "",
- "name": "My Engine",
- "message": "{hostname}:{deviceHostname} is online",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avOnline",
- "priority": 106,
- "triggerValue": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T13:19:35Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null
}, - {
- "id": "243e039d-0cf0-4efb-a88f-5ff342d45c95",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "",
- "name": "My Engine",
- "message": "{hostname}:{deviceHostname} is offline",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avOffline",
- "priority": 106,
- "triggerValue": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T13:19:25Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null
}, - {
- "id": "dfc444d7-1a6c-4ae2-9347-8d8acf7f349a",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "",
- "name": "My Site Director",
- "message": "{hostname}:{deviceHostname} is online",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avOnline",
- "priority": 106,
- "triggerValue": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T13:19:24Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null
}, - {
- "id": "ddf30e8e-ff6e-4036-b067-6e2617fa8244",
- "itemReference": "{hostname}:{deviceHostname}/AV3",
- "description": "",
- "name": "AV3",
- "alarmGeneratorObject": {
- "objectReference": "{hostname}:{deviceHostname}/AV3.Alarm1",
- "referencedObject": {
}
}, - "message": "",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avUnreliable",
- "priority": 70,
- "triggerValue": {
- "item": "2.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T13:19:22Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.generalCategory",
- "annotationsUrl": null
}, - {
- "id": "5b9a300d-d953-4e8f-902f-84da1c3d0deb",
- "itemReference": "{hostname}:{deviceHostname}",
- "description": "Dormant User Account",
- "name": "User Account I18NUser on device My Site Director",
- "message": "User Account has been unused or has not successfully logged in since 45 day(s)",
- "isAckRequired": true,
- "type": "alarmValueEnumSet.avAlarm",
- "priority": 220,
- "triggerValue": {
- "item": "66",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-08-31T12:53:53.977Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.systemCategory",
- "annotationsUrl": null
}
], - "effectivePermissions": [
- {
- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "cbc0a848-9231-4608-b958-276d3f2e9f3e",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "673c8b44-8667-4216-8856-e0d6c41aea6c",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "999235c5-9f4a-42f9-8ea5-863cc6a08eed",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "6e1d7f3b-226b-4b36-811f-849d8e32810d",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "f58f0068-f84a-4648-8ae7-bdf66c60994f",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "243e039d-0cf0-4efb-a88f-5ff342d45c95",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "dfc444d7-1a6c-4ae2-9347-8d8acf7f349a",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "ddf30e8e-ff6e-4036-b067-6e2617fa8244",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}, - {
- "id": "5b9a300d-d953-4e8f-902f-84da1c3d0deb",
- "canAcknowledge": true,
- "canDiscard": false,
- "canAnnotate": true
}
],
}Retrieves the specified alarm.
| alarmId required | string Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5 The identifier of the alarm. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/alarms/4d0598d4-2836-4efd-84b8-6f39754b1fc5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
An alarm for an analog value object.
{- "id": "4d0598d4-2836-4efd-84b8-6f39754b1fc5",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "description": "",
- "name": "AV2",
- "message": "",
- "isAckRequired": false,
- "type": "alarmValueEnumSet.avNormal",
- "priority": 200,
- "triggerValue": {
- "item": "1.0",
- "schema": {
- "type": "string",
- "metasysType": "string",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}
}
}, - "creationTime": "2021-09-01T17:00:07Z",
- "activityManagementStatus": "pending",
- "category": "objectCategoryEnumSet.administrativeCategory",
- "annotationsUrl": null,
- "spaces": [
- {
- "id": "d4c025db-db0e-56dc-910b-aa1d7bdbd723",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building.Floor 1",
- "name": "Floor 1",
}
], - "equipment": [
- {
- "id": "d40e96c6-d474-5aaf-be85-cfcbabb30334",
- "itemReference": "{hostname}:{deviceHostname}/equipment.My Engine",
- "equipmentName": "AHU",
- "shortName": "AV2",
}
]
}Allows for acknowledging or discarding an alarm.
| alarmId required | string Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5 The identifier of the alarm. |
| activityManagementStatus required | string Enum: "acknowledged" "discarded" The new activity management status of the alarm. The values of this property are described as follows:
|
| annotationText | string or null The annotation associated with the change of alarm state. |
{- "activityManagementStatus": "acknowledged"
}Retrieves the collection of annotations available for the specified alarm.
| alarmId required | string Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5 The identifier of the alarm. |
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" "user" "-user" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/alarms/4d0598d4-2836-4efd-84b8-6f39754b1fc5/annotations?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "total": 1,
- "next": null,
- "previous": null,
- "items": [
- {
- "id": 1,
- "text": "Looks okay",
- "user": "jane-doe",
- "creationTime": "2021-09-28T17:11:57.95Z",
- "action": "acknowledged",
}
],
}Adds an annotation to an alarm.
| alarmId required | string Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5 The identifier of the alarm. |
| text required | string [ 1 .. 255 ] characters \S The text of the annotation to create. This must not be |
{- "text": "Looks okay."
}How to retrieve, discard, and annotate audits.
Audits have relationships to other resources in the system. Find information about the most important below.
When users or the system affect objects in the Metasys system, such as analog inputs, multistate objects, or binary outputs, audits are generated. Those "acted upon" objects then relate to those audits. That relationship is returned as part of any audit response.
Equipment instance associations to audits build off of the objects association explanation. Each equipment instance can contain many points, such as Outdoor Air Temperature, Damper Position, or Zone Setpoint. Those points map to actual objects in Metasys, as noted above. When users or the system affect those objects, audits are generated. If an equipment instance's point is mapped to one of those affected objects the instance is then associated with that audit.
In short, an equipment instance contains points which map to Metasys objects which are affected by an audited action.
Space associations to audits build off of the equipment instance association explanation. Equipment instances can serve spaces, such as an Air Handler Unit (AHU) serving the floor of a building. Therefore, audits associated with a particular equipment instance are associated to the spaces they serve.
Retrieves a collection of audits for the specified object.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| originApplication | Array of strings Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp metasysEnum: auditOriginAppEnumSet Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message. The acceptable values for the elements of this parameter come from the See also:
|
| classLevel | Array of strings Example: classLevel=auditClassesEnumSet.userActionAuditClass metasysEnum: auditClassesEnumSet Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose. The Enabled Audit Level attribute ( The acceptable values for the elements of this parameter come from the See also:
|
| actionType | Array of strings Example: actionType=auditActionTypeEnumSet.writeAuditActionType metasysEnum: auditActionTypeEnumSet Filter by list of action types. The action type property indicates the user or system action performed. The acceptable values for the elements of this parameter come from the See also:
|
| user | Array of strings <= 100 items Example: user=metasysuser Filter by list of users. The user property indicates which user initiated the action being audited. |
| includeDiscarded | boolean Determines whether discarded audits will be included in the results.
|
| equipment | Array of strings <= 100 items Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398 Filter by list of equipment identifiers. |
| space | Array of strings <= 100 items Example: space=214f52d1-0c56-4a29-a690-abe5656d1647 Filter by list of space identifiers. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/audits?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser&includeDiscarded=false&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&space=214f52d1-0c56-4a29-a690-abe5656d1647&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Gets the first 10 audits.
{- "total": 400,
- "previous": null,
- "items": [
- {
- "id": "b11d01b5-52a4-4933-819b-d37ccac23d82",
- "creationTime": "2021-11-23T23:39:33.413Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful"
}, - {
- "id": "9b296b69-8dd1-479a-9f37-c19ac9c0f05b",
- "creationTime": "2021-11-23T23:39:27Z",
- "actionType": "auditActionTypeEnumSet.writeAuditActionType",
- "activityManagementStatus": "pending",
- "status": "statusEnumSet.ok",
- "preData": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "postData": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrUsageAnalyticsTermsAccepted"
}, - {
- "id": "59835997-50f3-4f20-aa51-f8dae14711b1",
- "creationTime": "2021-11-23T23:39:25.517Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful"
}, - {
- "id": "3a18fe31-8e80-4593-a134-fc39783a538e",
- "creationTime": "2021-11-23T23:39:19.29Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "metasyssysagent",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLogout"
}, - {
- "id": "ff522850-b94d-4caf-a796-02cd968b7538",
- "creationTime": "2021-11-23T23:39:15.663Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": {
- "item": "user: api_user",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": "metasyssysagent",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityPermissionsModified"
}, - {
- "id": "0438b847-4393-44b8-b48a-a50baf5fc6ad",
- "creationTime": "2021-11-23T23:39:15.633Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": {
- "item": "api_user",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": "metasyssysagent",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUpdateUserProperty"
}, - {
- "id": "f07dd325-762e-41f0-963c-916335737d9e",
- "creationTime": "2021-11-24T01:30:12.537Z",
- "actionType": "auditActionTypeEnumSet.commandAuditActionType",
- "activityManagementStatus": "pending",
- "status": "statusEnumSet.ok",
- "preData": null,
- "postData": null,
- "parameters": [
- {
- "item": "resetReasonEnumSet.downloadCompleteResetReason",
- "schema": {
- "type": "string",
- "metasysType": "enum",
}
}
], - "errorString": null,
- "user": null,
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.systemErrorAuditClass",
- "originApplication": "auditOriginAppEnumSet.deviceManagerAuditOriginApp",
- "description": "commandIdEnumSet.resetCommand"
}, - {
- "id": "a08f6706-02b5-45c6-81ec-0a03ea6d5dc8",
- "creationTime": "2021-11-23T23:38:37.117Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginFail"
}, - {
- "id": "15fafdd2-bd14-4207-ae83-406549fbd41e",
- "creationTime": "2021-11-24T01:22:40Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": null,
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.systemErrorAuditClass",
- "originApplication": "auditOriginAppEnumSet.deviceManagerAuditOriginApp",
- "description": "jciSystemStatusEnumSet.startupInProgress"
}, - {
- "id": "a6264199-ed92-4ca0-82fe-aec5914026a8",
- "creationTime": "2021-11-24T01:13:39.36Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "My Engine",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginFail"
}
], - "effectivePermissions": [
- {
- "id": "b11d01b5-52a4-4933-819b-d37ccac23d82",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "9b296b69-8dd1-479a-9f37-c19ac9c0f05b",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "59835997-50f3-4f20-aa51-f8dae14711b1",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "3a18fe31-8e80-4593-a134-fc39783a538e",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "ff522850-b94d-4caf-a796-02cd968b7538",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "0438b847-4393-44b8-b48a-a50baf5fc6ad",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "f07dd325-762e-41f0-963c-916335737d9e",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "a08f6706-02b5-45c6-81ec-0a03ea6d5dc8",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "15fafdd2-bd14-4207-ae83-406549fbd41e",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "a6264199-ed92-4ca0-82fe-aec5914026a8",
- "canDiscard": true,
- "canAnnotate": true
}
],
}Retrieves a collection of audits.
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| originApplication | Array of strings Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp metasysEnum: auditOriginAppEnumSet Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message. The acceptable values for the elements of this parameter come from the See also:
|
| classLevel | Array of strings Example: classLevel=auditClassesEnumSet.userActionAuditClass metasysEnum: auditClassesEnumSet Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose. The Enabled Audit Level attribute ( The acceptable values for the elements of this parameter come from the See also:
|
| actionType | Array of strings Example: actionType=auditActionTypeEnumSet.writeAuditActionType metasysEnum: auditActionTypeEnumSet Filter by list of action types. The action type property indicates the user or system action performed. The acceptable values for the elements of this parameter come from the See also:
|
| user | Array of strings <= 100 items Example: user=metasysuser Filter by list of users. The user property indicates which user initiated the action being audited. |
| includeDiscarded | boolean Determines whether discarded audits will be included in the results.
|
| equipment | Array of strings <= 100 items Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398 Filter by list of equipment identifiers. |
| object | Array of strings <= 100 items Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7 Filter by list of object identifiers. |
| space | Array of strings <= 100 items Example: space=214f52d1-0c56-4a29-a690-abe5656d1647 Filter by list of space identifiers. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/audits?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser&includeDiscarded=false&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Gets the first 10 audits.
{- "total": 400,
- "previous": null,
- "items": [
- {
- "id": "b11d01b5-52a4-4933-819b-d37ccac23d82",
- "creationTime": "2021-11-23T23:39:33.413Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful"
}, - {
- "id": "9b296b69-8dd1-479a-9f37-c19ac9c0f05b",
- "creationTime": "2021-11-23T23:39:27Z",
- "actionType": "auditActionTypeEnumSet.writeAuditActionType",
- "activityManagementStatus": "pending",
- "status": "statusEnumSet.ok",
- "preData": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "postData": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrUsageAnalyticsTermsAccepted"
}, - {
- "id": "59835997-50f3-4f20-aa51-f8dae14711b1",
- "creationTime": "2021-11-23T23:39:25.517Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful"
}, - {
- "id": "3a18fe31-8e80-4593-a134-fc39783a538e",
- "creationTime": "2021-11-23T23:39:19.29Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "metasyssysagent",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLogout"
}, - {
- "id": "ff522850-b94d-4caf-a796-02cd968b7538",
- "creationTime": "2021-11-23T23:39:15.663Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": {
- "item": "user: api_user",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": "metasyssysagent",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityPermissionsModified"
}, - {
- "id": "0438b847-4393-44b8-b48a-a50baf5fc6ad",
- "creationTime": "2021-11-23T23:39:15.633Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": {
- "item": "api_user",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": "metasyssysagent",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUpdateUserProperty"
}, - {
- "id": "f07dd325-762e-41f0-963c-916335737d9e",
- "creationTime": "2021-11-24T01:30:12.537Z",
- "actionType": "auditActionTypeEnumSet.commandAuditActionType",
- "activityManagementStatus": "pending",
- "status": "statusEnumSet.ok",
- "preData": null,
- "postData": null,
- "parameters": [
- {
- "item": "resetReasonEnumSet.downloadCompleteResetReason",
- "schema": {
- "type": "string",
- "metasysType": "enum",
}
}
], - "errorString": null,
- "user": null,
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.systemErrorAuditClass",
- "originApplication": "auditOriginAppEnumSet.deviceManagerAuditOriginApp",
- "description": "commandIdEnumSet.resetCommand"
}, - {
- "id": "a08f6706-02b5-45c6-81ec-0a03ea6d5dc8",
- "creationTime": "2021-11-23T23:38:37.117Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": {
- "item": "::1",
- "schema": {
- "type": "string",
- "metasysType": "string"
}
}, - "parameters": [ ],
- "errorString": null,
- "user": "api_user",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
- "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginFail"
}, - {
- "id": "15fafdd2-bd14-4207-ae83-406549fbd41e",
- "creationTime": "2021-11-24T01:22:40Z",
- "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
- "activityManagementStatus": "pending",
- "status": null,
- "preData": null,
- "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": null,
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}",
- "objectName": "{deviceHostname}",
- "classLevel": "auditClassesEnumSet.systemErrorAuditClass",
- "originApplication": "auditOriginAppEnumSet.deviceManagerAuditOriginApp",
- "description": "jciSystemStatusEnumSet.startupInProgress"
}, - {
- "id": "a6264199-ed92-4ca0-82fe-aec5914026a8",
- "creationTime": "2021-11-24T01:13:39.36Z",
- "actionType": "auditActionTypeEnumSet.createAuditActionType",
- "activityManagementStatus": "pending",
- "status": "statusEnumSet.ok",
- "preData": null,
- "postData": null,
- "parameters": [ ],
- "errorString": null,
- "user": "IntraComputer",
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}/$GenericArchive.GraphicAssets.Shared.Template",
- "objectName": "Shared Template",
- "classLevel": "auditClassesEnumSet.userActionAuditClass",
- "originApplication": "auditOriginAppEnumSet.generalAuditOriginApp",
- "description": null
}
], - "effectivePermissions": [
- {
- "id": "b11d01b5-52a4-4933-819b-d37ccac23d82",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "9b296b69-8dd1-479a-9f37-c19ac9c0f05b",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "59835997-50f3-4f20-aa51-f8dae14711b1",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "3a18fe31-8e80-4593-a134-fc39783a538e",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "ff522850-b94d-4caf-a796-02cd968b7538",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "0438b847-4393-44b8-b48a-a50baf5fc6ad",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "f07dd325-762e-41f0-963c-916335737d9e",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "a08f6706-02b5-45c6-81ec-0a03ea6d5dc8",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "15fafdd2-bd14-4207-ae83-406549fbd41e",
- "canDiscard": true,
- "canAnnotate": true
}, - {
- "id": "a6264199-ed92-4ca0-82fe-aec5914026a8",
- "canDiscard": true,
- "canAnnotate": true
}
],
}Retrieves the specific audit.
| auditId required | string Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c The identifier of the audit. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/audits/4990ee27-7a0a-4b2b-9b27-279e3f1a060c \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
An audit for an analog value object.
{- "id": "6c6ae3dd-c514-423d-bd22-0b48678c5384",
- "creationTime": "2021-12-10T21:05:53Z",
- "actionType": "auditActionTypeEnumSet.commandAuditActionType",
- "activityManagementStatus": "pending",
- "status": "statusEnumSet.ok",
- "spaces": [ ],
- "equipment": [ ],
- "preData": {
- "item": 52,
- "schema": {
- "type": "number",
- "metasysType": "float",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}
}
}, - "postData": null,
- "parameters": [
- {
- "item": 50,
- "schema": {
- "type": "number",
- "metasysType": "float",
- "units": {
- "id": "unitEnumSet.noUnits",
- "title": ""
}, - "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}
}
}
], - "errorString": null,
- "user": null,
- "signature": null,
- "itemReference": "{hostname}:{deviceHostname}/AV1",
- "objectName": "Interlock1/AV1",
- "classLevel": "auditClassesEnumSet.applicationAuditClass",
- "originApplication": "auditOriginAppEnumSet.interlockAuditOriginApp",
- "description": "commandIdEnumSet.adjustCommand"
}Allows for discarding an audit.
| auditId required | string Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c The identifier of the audit. |
| activityManagementStatus required | string Value: "discarded" The new activity management status of the audit. The only accepted value of this property is |
| annotationText | string or null The annotation to associate with the change of audit state. |
{- "activityManagementStatus": "discarded"
}Retrieves the collection of annotations available for the specified audit.
| auditId required | string Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c The identifier of the audit. |
| startTime | string <date-time> Example: startTime=2018-05-21T13:58:20.243Z Only include results generated on or after this date-time. |
| endTime | string <date-time> Example: endTime=2018-05-21T13:58:20.243Z Only include results generated on or before this date-time. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 10000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "creationTime" Enum: "creationTime" "-creationTime" Example: sort=creationTime The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/audits/4990ee27-7a0a-4b2b-9b27-279e3f1a060c/annotations?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=100&sort=creationTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "total": 1,
- "next": null,
- "previous": null,
- "items": [
- {
- "id": 2,
- "creationTime": "2021-09-28T19:00:48.043Z",
- "user": "jane-doe",
- "signature": null,
- "action": "discarded"
}
],
}Adds an annotation to an audit.
| auditId required | string Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c The identifier of the audit. |
| text required | string [ 1 .. 255 ] characters \S The text of the annotation to create. This must not be |
{- "text": "Looks okay."
}Retrieves a list of unique usernames from all users present in a currently stored audit. The provided usernames may or may not reflect known users of the current system, but were known when the system recorded an audit for them.
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/audits/users \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "items": [
- "aaron",
- "brian",
- "chris",
- "diana",
- "emily"
], - "total": 5,
}Use this to request an access token that can be used for authentication on other API calls.
Used to supply credentials for login.
| username | string The user name of a Metasys account. |
| password | string The corresponding password of a Metasys account. |
{- "username": "jane-doe",
- "password": "strongPassword"
}The result includes the access token needed to make requests. (The token in this example has been truncated.)
{- "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
- "expires": "2021-04-22T00:12:18Z"
}Use this operation to request a new token before the previous one expires.
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/refreshToken \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The result includes the access token needed to make requests. (The token in this example has been truncated.)
{- "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
- "expires": "2021-04-22T00:12:18Z"
}Retrieve the binary CSR data for a single device. A successful (200) response provides the CSR in a PEM format.
Note: This endpoint is intended to support
application/vnd.metasysapi.v5+json and application/octet-stream MIME types
via the Accept header however neither of these are currently supported.
Only application/pkcs10 is supported even though it shouldn't be.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| If-None-Match | string Example: DrIITJxrrFDVYbFrmM41X6xj/v+HlD/QgWuvNeIPCvM= A previous |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/signingRequests/bacnet \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'If-None-Match: DrIITJxrrFDVYbFrmM41X6xj/v+HlD/QgWuvNeIPCvM='
A certificate signing request in PEM format meant for a raw output (a MIME
type of application/octet-stream).
-----BEGIN CERTIFICATE REQUEST----- MIIBlTCCARwCAQIwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXSTESMBAGA1UE BwwJTWlsd2F1a2VlMRkwFwYDVQQKDBBKb2huc29uIENvbnRyb2xzMREwDwYDVQQL DAhDb250cm9sczEYMBYGA1UEAwwPTUFDMDI0MkFDMTUxNzA2MSQwIgYJKoZIhvcN AQkBFhVqYWNvYi5wLmhpY2tzQGpjaS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNi AASv3V9GGmXQqNmTCKIZPy4unQBGPDYG6RzqybRrJO6ZSVTm31y1XYuvFIE0u+I3 NrtpR0DPDCvfDlecQkEpkgB5roIijDh7/ZEKDwQgvc8pvxWVzCv7OQw4OoCK1bd8 SXOgADAKBggqhkjOPQQDAgNnADBkAjBoC8P9g/2r9yS1MR9H4iv/f3uvbzP8PQd3 4PJdATJjZsHWVml1E42DEK5ejQDl6rICMFLNL5Mwf029d9v+/X2UvrZ12TJDC8nx 2ZrcTdE6zw5cyxVwR9xyJ8YqU35iqvsTmA== -----END CERTIFICATE REQUEST-----
Create a new certificate signing request (CSR) for the specified device and CSR parameters. A successful (201) response provides the CSR in a PEM format.
Note: This endpoint is intended to support
application/vnd.metasysapi.v5+json and application/octet-stream MIME types
via the Accept header however neither of these are currently supported.
Only application/pkcs10 is supported even though it shouldn't be.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| emailAddress required | string <email> [ 1 .. 63 ] characters |
| orgName required | string [ 1 .. 63 ] characters |
| orgUnitName required | string [ 1 .. 63 ] characters |
| city required | string [ 1 .. 63 ] characters |
| stateProvince required | string [ 1 .. 63 ] characters |
| country required | string = 2 characters |
| domainName | string or null [ 1 .. 47 ] characters |
{- "city": "Milwaukee",
- "country": "US",
- "emailAddress": "noreply@jci.com",
- "orgName": "Johnson Controls",
- "orgUnitName": "BAS",
- "stateProvince": "WI",
- "domainName": "jci.com"
}A certificate signing request in PEM format meant for a raw output (a MIME
type of application/octet-stream).
-----BEGIN CERTIFICATE REQUEST----- MIIBlTCCARwCAQIwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXSTESMBAGA1UE BwwJTWlsd2F1a2VlMRkwFwYDVQQKDBBKb2huc29uIENvbnRyb2xzMREwDwYDVQQL DAhDb250cm9sczEYMBYGA1UEAwwPTUFDMDI0MkFDMTUxNzA2MSQwIgYJKoZIhvcN AQkBFhVqYWNvYi5wLmhpY2tzQGpjaS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNi AASv3V9GGmXQqNmTCKIZPy4unQBGPDYG6RzqybRrJO6ZSVTm31y1XYuvFIE0u+I3 NrtpR0DPDCvfDlecQkEpkgB5roIijDh7/ZEKDwQgvc8pvxWVzCv7OQw4OoCK1bd8 SXOgADAKBggqhkjOPQQDAgNnADBkAjBoC8P9g/2r9yS1MR9H4iv/f3uvbzP8PQd3 4PJdATJjZsHWVml1E42DEK5ejQDl6rICMFLNL5Mwf029d9v+/X2UvrZ12TJDC8nx 2ZrcTdE6zw5cyxVwR9xyJ8YqU35iqvsTmA== -----END CERTIFICATE REQUEST-----
Replace the certificate signing request (CSR) for the specified device and CSR parameters. A successful (200) response provides the CSR in a PEM format.
Note: This endpoint is intended to support
application/vnd.metasysapi.v5+json and application/octet-stream MIME types
via the Accept header however neither of these are currently supported.
Only application/pkcs10 is supported even though it shouldn't be.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| If-Match required | string Example: 33a64df551425fcc55e4d42a148795d9f25f89d4 A previous |
| emailAddress required | string <email> [ 1 .. 63 ] characters |
| orgName required | string [ 1 .. 63 ] characters |
| orgUnitName required | string [ 1 .. 63 ] characters |
| city required | string [ 1 .. 63 ] characters |
| stateProvince required | string [ 1 .. 63 ] characters |
| country required | string = 2 characters |
| domainName | string or null [ 1 .. 47 ] characters |
{- "city": "Milwaukee",
- "country": "US",
- "emailAddress": "noreply@jci.com",
- "orgName": "Johnson Controls",
- "orgUnitName": "BAS",
- "stateProvince": "WI",
- "domainName": "jci.com"
}A certificate signing request in PEM format meant for a raw output (a MIME
type of application/octet-stream).
-----BEGIN CERTIFICATE REQUEST----- MIIBlTCCARwCAQIwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXSTESMBAGA1UE BwwJTWlsd2F1a2VlMRkwFwYDVQQKDBBKb2huc29uIENvbnRyb2xzMREwDwYDVQQL DAhDb250cm9sczEYMBYGA1UEAwwPTUFDMDI0MkFDMTUxNzA2MSQwIgYJKoZIhvcN AQkBFhVqYWNvYi5wLmhpY2tzQGpjaS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNi AASv3V9GGmXQqNmTCKIZPy4unQBGPDYG6RzqybRrJO6ZSVTm31y1XYuvFIE0u+I3 NrtpR0DPDCvfDlecQkEpkgB5roIijDh7/ZEKDwQgvc8pvxWVzCv7OQw4OoCK1bd8 SXOgADAKBggqhkjOPQQDAgNnADBkAjBoC8P9g/2r9yS1MR9H4iv/f3uvbzP8PQd3 4PJdATJjZsHWVml1E42DEK5ejQDl6rICMFLNL5Mwf029d9v+/X2UvrZ12TJDC8nx 2ZrcTdE6zw5cyxVwR9xyJ8YqU35iqvsTmA== -----END CERTIFICATE REQUEST-----
Clear any existing certificate signing request (CSR) for the specified device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| If-Match required | string Example: 33a64df551425fcc55e4d42a148795d9f25f89d4 A previous |
curl --request DELETE \ --url https:///%7Bhostname%7D/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/signingRequests/bacnet \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'If-Match: 33a64df551425fcc55e4d42a148795d9f25f89d4'
{- "statusName": "string",
- "code": "string",
- "message": "string",
- "details": { },
- "innerError": { },
- "innerErrors": [
- { }
]
}Retrieve the raw and/or structured certificate data for a single device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| flatten | boolean Default: true Example: flatten=true Return the certificates as a flat list or as nested trees. When nested, the result items will have an |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/certificates/bacnet?flatten=true' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Certificate details as a list. Note that JSON must encode new lines (\n) for the raw property.
{- "items": [
- {
- "id": "7EEC06D24877B4D191FA463D358609CC20289D4F",
- "issuer": "CN=Metasys Test CA",
- "subject": "C=US, S=WI, L=MKE, O=JCI, OU=BE, CN=MAC02427035AC6D, E=test@testAll.com",
- "validFrom": "2021-04-19T22:06:37Z",
- "validUntil": "2022-03-30T19:45:10Z",
- "authorityKeyId": "4131D4F94A1D71243E624FFC20468F023440FA7A",
- "subjectKeyId": "2EE21E21D641AAA23042F20FE13FD12A95831A85",
- "serialNumber": "00B9431D8F2B149691",
- "raw": "-----BEGIN CERTIFICATE-----\nMIICJjCCAcugAwIBAgIJALlDHY8rFJaRMAoGCCqGSM49BAMCMBoxGDAWBgNVBAMT\nD01ldGFzeXMgVGVzdCBDQTAeFw0yMTA0MTkyMjA2MzdaFw0yMjAzMzAxOTQ1MTBa\nMH4xHzAdBgkqhkiG9w0BCQEWEHRlc3RAdGVzdEFsbC5jb20xGDAWBgNVBAMTD01B\nQzAyNDI3MDM1QUM2RDELMAkGA1UECxMCQkUxDDAKBgNVBAoTA0pDSTEMMAoGA1UE\nBxMDTUtFMQswCQYDVQQIEwJXSTELMAkGA1UEBhMCVVMwdjAQBgcqhkjOPQIBBgUr\ngQQAIgNiAARei12VLrNFW9ThXWbuP9jjgqumm+qRbYmjRr2Eft09gzcn9fSZyr7g\npmUZVsTeEbzzkAJDDFVobQ4iis5iXD8iAs/h4DkFc5eoXmS5hWGL3n5VPLfE1hCB\nD6HZCVGmd/6jeTB3MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgWgMB0GA1UdJQQWMBQG\nCCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQULuIeIdZBqqIwQvIP4T/RKpWD\nGoUwHwYDVR0jBBgwFoAUQTHU+UodcSQ+Yk/8IEaPAjRA+nowCgYIKoZIzj0EAwID\nSQAwRgIhAOBqzqlMJtoTvQxH0qx1s6oVY1NvsyXthO9SZlwlYEkeAiEAwyU0/jgU\nNaHD0eqyywHZxyQto1vTscCbTJZIuFOVGnk=\n-----END CERTIFICATE-----\n"
}, - {
- "id": "1535878BEAFA6F37273548BB0024FAE212C8759B",
- "issuer": "CN=Metasys Test CA",
- "subject": "CN=Metasys Test CA",
- "validFrom": "2021-03-29T19:45:10Z",
- "validUntil": "2022-03-30T19:45:10Z",
- "authorityKeyId": "4131D4F94A1D71243E624FFC20468F023440FA7A",
- "subjectKeyId": "4131D4F94A1D71243E624FFC20468F023440FA7A",
- "serialNumber": "00D5218FE0248E8D25",
- "raw": "-----BEGIN CERTIFICATE-----\nMIIBpzCCAU2gAwIBAgIJANUhj+Akjo0lMAoGCCqGSM49BAMCMBoxGDAWBgNVBAMT\nD01ldGFzeXMgVGVzdCBDQTAeFw0yMTAzMjkxOTQ1MTBaFw0yMjAzMzAxOTQ1MTBa\nMBoxGDAWBgNVBAMTD01ldGFzeXMgVGVzdCBDQTBZMBMGByqGSM49AgEGCCqGSM49\nAwEHA0IABDDE4n8dfuug8nHErsHyEGO6FQZ56Kyv+tCiUnDJpULs86y2/HXEejxr\ntU4UgTbt5YJCxu7cPI+TYmMfyjwG3WyjfDB6MAwGA1UdEwQFMAMBAf8wCwYDVR0P\nBAQDAgKkMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQU\nQTHU+UodcSQ+Yk/8IEaPAjRA+nowHwYDVR0jBBgwFoAUQTHU+UodcSQ+Yk/8IEaP\nAjRA+nowCgYIKoZIzj0EAwIDSAAwRQIgH/C7cCPvP3kqVI0oSpKmRgQOJZOK+X9h\nZjtL1/6pPbsCIQDGIC2Y4jfEKvyFB1g1RIftdmOManZbbYb+6FTbWgczYA==\n-----END CERTIFICATE-----\n"
}
]
}Write the raw certificate data for a single device. The data may be a single operational certificate or the entire chain.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
A certificate in PEM format.
-----BEGIN CERTIFICATE----- MIICJjCCAcugAwIBAgIJALlDHY8rFJaRMAoGCCqGSM49BAMCMBoxGDAWBgNVBAMT D01ldGFzeXMgVGVzdCBDQTAeFw0yMTA0MTkyMjA2MzdaFw0yMjAzMzAxOTQ1MTBa MH4xHzAdBgkqhkiG9w0BCQEWEHRlc3RAdGVzdEFsbC5jb20xGDAWBgNVBAMTD01B QzAyNDI3MDM1QUM2RDELMAkGA1UECxMCQkUxDDAKBgNVBAoTA0pDSTEMMAoGA1UE BxMDTUtFMQswCQYDVQQIEwJXSTELMAkGA1UEBhMCVVMwdjAQBgcqhkjOPQIBBgUr gQQAIgNiAARei12VLrNFW9ThXWbuP9jjgqumm+qRbYmjRr2Eft09gzcn9fSZyr7g pmUZVsTeEbzzkAJDDFVobQ4iis5iXD8iAs/h4DkFc5eoXmS5hWGL3n5VPLfE1hCB D6HZCVGmd/6jeTB3MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgWgMB0GA1UdJQQWMBQG CCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQULuIeIdZBqqIwQvIP4T/RKpWD GoUwHwYDVR0jBBgwFoAUQTHU+UodcSQ+Yk/8IEaPAjRA+nowCgYIKoZIzj0EAwID SQAwRgIhAOBqzqlMJtoTvQxH0qx1s6oVY1NvsyXthO9SZlwlYEkeAiEAwyU0/jgU NaHD0eqyywHZxyQto1vTscCbTJZIuFOVGnk= -----END CERTIFICATE-----
{- "statusName": "string",
- "code": "string",
- "message": "string",
- "details": { },
- "innerError": { },
- "innerErrors": [
- { }
]
}Delete the certificate(s) for a single device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| loose | boolean Default: true Example: loose=true If Note: Only |
curl --request DELETE \ --url 'https:///%7Bhostname%7D/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/certificates/bacnet?loose=true' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "statusName": "string",
- "code": "string",
- "message": "string",
- "details": { },
- "innerError": { },
- "innerErrors": [
- { }
]
}Write a collection of raw certificate data to the devices associated to the included certificates.
A ZIP file which must contain 1 or more operational certificates and their issuer certificate(s). The issuer certificate(s) may be a separate file or included with each operational certificate (known as a PKCS #7 file).
curl --request POST \ --url https:///%7Bhostname%7D/api/v5/networkDevices/certificates/bacnet \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Import BACnet/SC certificates success response
[- {
- "certificate": "filename1.pem",
- "detectedType": "operational",
- "deviceId": "31469a3d-44da-4aa3-8f26-ec5753e0f23d",
- "status": "applied"
}, - {
- "certificate": "filename2.pem",
- "detectedType": "operational",
- "deviceId": null,
- "status": "deviceNotFound"
}, - {
- "certificate": "signing.pem",
- "detectedType": "issuer",
- "deviceId": null,
- "status": "issuer"
}
]Operations on control objects.
Some controls may have a visual representation known as a diagram. While a diagram is a visual representation, it is more importantly the means by which control logic is defined for some types of controls.
A diagram contains 3 general elements - blocks, ports, and connections.
A block generally represents some primitive function, such as an add operation. Most blocks work upon some number of input ports and provide the result via output ports. Blocks may have additional configuration to them as well.
The ports of blocks can be connected via connections to pass values from a source to a destination.
Every block in a diagram is defined by a schema. A schema defines what the available properties and ports are available on a block. The properties and ports have associated metadata to define value types and value constraints.
A block schema is a JSON Schema, with some custom keywords:
sequenceProperties - indicates that all properties defined under it should
be generated from a sequence of integer values. Every property name should be
a format string which includes {n} as a placeholder to where the sequence
number is populated. The source of the sequence numbering is defined by a
countSource property, which defines how many properties are currently
defined in the instance data that follow a templated sequence. This value
should resolve to a property of the block. The schema of the countSource
property should always be of type "integer", have a non-negative minimum,
and have a maximum.Diagrams may be subscribed to for streaming events by a client. A subscription
is established by providing a METASYS-SUBSCRIBE header with the GET
operation of a diagram.
See also:
To subscribe to a diagram use the Get diagram operation
and include a METASYS-SUBSCRIBE header. The value of this header should be the
stream id you received when you opened a stream.
Here are the types of events sent by the diagram subscription along with example
data payloads for each.
diagram.subscription.established - Indicates when a subscription has been
established for the diagram.
{
"id": "d7861b6a-d563-5521-a746-a68519cb7651",
"subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"],
"message": "Live value subscription successful"
}
diagram.subscription.cancelled - Indicates when a subscription has been
cancelled for the diagram.
{
"id": "d7861b6a-d563-5521-a746-a68519cb7651",
"subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
"message": "Live value subscription cancelled"
}
diagram.values.update - Indicates a change in value of blocks or ports
within the diagram. The first occurrence of this event will include all values
in the diagram. Subsequent occurrences will only include values that changed
from the previous occurrence.
{
"id": "d7861b6a-d563-5521-a746-a68519cb7651",
"subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"],
"items": [
["8", 2.0],
["9", 2.0, { "reliability": "reliabilityEnumSet.writeError" }]
]
}
Each entry in items is a tuple of 2 or 3 values:
id property of the diagram entity.null.The first diagram.values.update event payload for a new subscription of a
diagram will contain all current values of entities in the diagram. Subsequent
events will only contain values that changed from the previous event.
diagram.error - Indicates an error occurred during cancelling a
subscription.
{
"subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
"message": "Error while cancelling subscription"
}
diagram.heartbeat - Indicates that the logic service is alive.
"ping from logic service @2021-08-04T16:03:23.3771485Z"
diagram.update - Indicates a change in the structure of the diagram. This
event will cause the subscription to be cancelled.
{
"id": "d7861b6a-d563-5521-a746-a68519cb7651",
"subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
"message": "The diagram has been updated.. Please refresh. Current subscription will be cancelled automatically."
}
An instance of a control is really an instance of an object available at the
relative URL of /objects/{objectId}. As a control, the representation of the
object is more aligned with control logic in an abstracted manner rather than a
more primitive and more complex representation.
Retrieves the diagram of the specified control instance.
If the METASYS-SUBSCRIBE header is provided, then an event subscription
will be created which will include the events described in
Diagrams
| controlId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the control. |
| includeSchema | boolean Default: false Indicates whether the schema of the diagram should also be returned. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/controls/5a22812f-ec51-4c11-ab4a-fc986f94f008/diagram?includeSchema=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Shows the results of a diagram with no blocks or connections.
{- "id": "5a22812f-ec51-4c11-ab4a-fc986f94f008",
- "name": "System1",
- "environment": {
- "engine": "lct",
- "engineVersion": "1.0",
- "maximums": {
- "inputs": {
- "allOf": [
- "input-float",
- "input-boolean",
- "input-enumeration"
], - "maximum": 24
}, - "outputs": {
- "allOf": [
- "output-float",
- "output-boolean",
- "output-enumeration"
], - "maximum": 24
}
}
}, - "item": {
- "blocks": [ ],
- "connections": [ ]
}
}Replaces the diagram of the specified control instance.
There are a variety of errors that are possible when attempting to update a diagram. Every known error that can be determined will be communicated in a response. The error response is hierarchical such that the top-most errors describe generalized issues while inner-most errors describe specific issues. Each error is intended to be self-descriptive with accompanying details.
api.diagram:error.saveFailed
The save failed. innerError or innerErrors will have more information
api.diagram:error.schemaFailure
The payload did not validate against the schema.
api.diagram:error.diagramSchemaFailure
The diagram did not validate against the schema.
api.diagram:error.invalidSchemaUrl
A block's schema URL is invalid or doesn't reference a known block type.
api.diagram:error.blockSchemaFailure
A block did not validate against its schema.
api.diagram:error.connectionSchemaFailure
A connection did not validate against its schema.
api.diagram:error.unboundReferences
The configured object reference for an Input Reference or Output Reference could not be resolved.
enum.core:statusEnumSet.writeAccessDeniedSecurity
The user is not authorized to modify the diagram.
api.diagram:error.unauthorizedExistingDiagram
The user is not authorized to modify the existing diagram.
api.diagram:error.unauthorizedRequestDiagram
The user is not authorized to control some references in the new diagram.
api.diagram:error.duplicateId
The same id is defined multiple times in the diagram.
api.diagram:error.circularLogic
An unsupported circular loop has been defined in the diagram.
api.diagram:error.ioAttributes
A general wrapper for any errors related to Input Attributes and Output Attributes.
api.diagram:error.ioThresholdExceeded
The diagram contains more than the maximum allowed inputs or outputs.
api.diagram:error.duplicateIOBlockName
The diagram contains duplicate Input Attribute and Output Attribute names.
api.diagram:error.duplicateIOAttribute
The diagram contains duplicate Input Attribute and Output Attribute identifiers.
api.diagram:error.connection
A general wrapper for any errors related to a connection.
api.diagram:error.portDoesNotExist
The port referenced by a connection's source or destination is not defined.
api.diagram:error.portsCannotBeFromSameBlock
A connection's source and destination cannot be from the same block.
api.diagram:error.delayConnectedToOutputTypeBlock
A Delay block should not be connected to an Output Reference or Output Attribute.
api.diagram:error.priorityNotSupported
A connection does not support priority when connected to anything other than Output Reference.
api.diagram:error.portDirectionInvalidForConnectionEndpoint
The source of a connection cannot be an input port of a block and the destination of a connection cannot be an output port of a block.
api.diagram:error.block
A general wrapper for any errors related to a block.
api.diagram:error.invalidEnum
An enumeration value is not valid.
api.diagram:error.duplicatePortInSubSystem
A System block cannot define a port as both being an input and an output.
api.diagram:error.portDoesNotExistInSubSystem
A System block exposes a port which is not defined.
api.diagram:error.inPortIsNotWritableInSubSystem
A System block exposes a input port which is not writable.
api.diagram:error.limitsCountMismatchInSequencer
A Sequencer block doesn't have the same number of make limit values as break limit values.
api.diagram:error.limitsDoesNotMatchOutputsInSequencer
A Sequencer block must have the same number of make & break limit values
as the number of outputs. If proactive is true, then the expected
count of limit values should be one less than the number of outputs.
api.diagram:error.limitsNotInAscendingOrderInSequencer
A Sequencer block must have make & break limit values in ascending order.
api.diagram:error.breakIsGreaterThanMakeInSequencer
A Sequencer block must have break limits which are less than their corresponding make limit of the same stage.
api.diagram:error.makeIsGreaterThanBreakInSequencer
A Sequencer block must have make limits which are less than the break limit of the previous stage.
api.diagram:error.duplicateModeSelectionInMux
A Multiplexor (MUX) block cannot use the same mode enumeration value multiple times.
| controlId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the control. |
The desired blocks and connections of the diagram. This is the same
structure as the item property from the GET /diagram response.
required | object (Diagram) A set of blocks and connections which make up an instance of programmable control logic. |
A diagram with no blocks or connections.
{- "item": {
- "blocks": [ ],
- "connections": [ ]
}
}Shows the response of a replace diagram request which had no item property.
{- "statusName": "api.diagram:error.saveFailed",
- "message": "Diagram save failed. Please see innerError(s) for more information.",
- "innerError": {
- "statusName": "api.diagram:error.schemaFailure",
- "message": "Schema validation failed for diagram. Please see innerError(s) for more information.",
- "innerError": {
- "statusName": "api.diagram:error.diagramSchemaFailure",
- "message": "Diagram instance failed schema validation. Please see details for more information.",
- "details": {
- "valid": false,
- "errors": [
- {
- "valid": false,
- "keywordLocation": "#/required",
- "instanceLocation": "#",
- "keyword": "required",
- "additionalInfo": {
- "missing": [
- "item"
]
}
}
]
}
}
}
}Deletes a subscription to a control resource.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
curl --request DELETE \ --url https:///%7Bhostname%7D/api/v5/controls/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Retrieves a palette, which defines the available types of blocks available to diagramming.
| paletteId required | string Example: 01443cbc-d65e-4666-85d5-484a3b1f4f21 The identifier of the palette. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/controls/palettes/01443cbc-d65e-4666-85d5-484a3b1f4f21 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
An LCT palette (this is only a partial example).
{- "id": "01443cbc-d65e-4666-85d5-484a3b1f4f21",
- "name": "Core LCT Palette",
- "items": [
- {
- "id": "tool",
- "name": "Tools",
- "description": "A free form block of text.",
- "type": "text.",
- "definitions": [
- {
- "title": "Text",
- "description": "The schema for a text block instance",
- "type": "object",
- "properties": {
- "id": {
- "type": "integer",
- "minimum": 1
}, - "schemaUrl": {
- "type": "string",
- "format": "uri",
}, - "location": {
- "type": "object",
- "properties": {
- "x": {
- "type": "number"
}, - "y": {
- "type": "number"
}
}, - "required": [
- "x",
- "y"
]
}, - "text": {
- "type": "string",
- "metasysType": "string",
- "pattern": "^[^:\\\"]*$",
- "default": "Untitled"
}, - "width": {
- "type": "number",
- "metasysType": "float",
- "default": 40,
- "minimum": 1,
- "maximum": 3.40282347e+38
}
}, - "required": [
- "id",
- "schemaUrl",
- "location",
- "text"
], - "additionalProperties": false,
- "views": [
- {
- "id": "viewNameEnumSet.configView",
- "title": "Configuration",
- "views": [
- {
- "id": "groupTypeEnumSet.basicGrpType",
- "title": "Basic",
- "views": [
- {
- "id": "viewGroupEnumSet.displayGrp",
- "title": "Display",
- "properties": [
- "text"
]
}
]
}
]
}
]
}
]
}
]
}Retrieves the schema for a specific block type.
| paletteId required | string Example: 01443cbc-d65e-4666-85d5-484a3b1f4f21 The identifier of the palette. |
| blockDefinitionId required | string Examples:
The ID of the block definition to get the schema for. The ID is the last
portion of the |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/controls/palettes/01443cbc-d65e-4666-85d5-484a3b1f4f21/text \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The Text Block definition on the LCT palette.
{- "title": "Text",
- "description": "The schema for a text block instance",
- "type": "object",
- "properties": {
- "id": {
- "type": "integer",
- "minimum": 1
}, - "schemaUrl": {
- "type": "string",
- "format": "uri",
}, - "location": {
- "type": "object",
- "properties": {
- "x": {
- "type": "number"
}, - "y": {
- "type": "number"
}
}, - "required": [
- "x",
- "y"
]
}, - "text": {
- "type": "string",
- "metasysType": "string",
- "pattern": "^[^:\\\"]*$",
- "default": "Untitled"
}, - "width": {
- "type": "number",
- "metasysType": "float",
- "default": 40,
- "minimum": 1,
- "maximum": 3.40282347e+38
}
}, - "required": [
- "id",
- "schemaUrl",
- "location",
- "text"
], - "additionalProperties": false,
- "views": [
- {
- "id": "viewNameEnumSet.configView",
- "title": "Configuration",
- "views": [
- {
- "id": "groupTypeEnumSet.basicGrpType",
- "title": "Basic",
- "views": [
- {
- "id": "viewGroupEnumSet.displayGrp",
- "title": "Display",
- "properties": [
- "text"
]
}
]
}
]
}
]
}Enumerations are an important data type used by Metasys®. A single enumeration is used to define a set of values a property can have and each value includes a localized string to describe itself.
| enumType | string Default: "all" Enum: "all" "twoState" "multiState" "custom" Examples:
The type of enumerations to return. |
| minNumberOfStates | integer Example: minNumberOfStates=4 Filter the result to include only those multi-state and custom enumerations with at least the specified |
| includePermissions | boolean Default: false Include effective permissions for the client with respect to enumerations. |
| Accept-Language | Array of strings Example: en-US, de-De The language to use for display text of enumeration name and members. If no language is specified the client's default language as specified in their user profile will be used. |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/enumerations?enumType=all&minNumberOfStates=4&includePermissions=false' \ --header 'Accept-Language: en-US, de-De'
{- "items": {
- "customEnumSet30001": {
- "isMultiState": true,
- "isMutable": true,
- "name": "Speed",
- "numberOfStates": 3
}, - "customEnumSet30002": {
- "isTwoState": true,
- "isMutable": true,
- "name": "Rotation"
}
}
}Create a custom enumeration with members of your choice
New enumeration
required | object An enumeration |
{- "item": {
- "name": "Speed",
- "members": [
- "Slow",
- "Fast",
- "Very Fast"
]
}
}{- "item": {
- "name": "Speed",
- "members": {
- "customEnumSet30001.0": {
- "value": 0,
- "name": "Slow"
}, - "customEnumSet30001.1": {
- "value": 1,
- "name": "Fast"
}, - "customEnumSet30001.2": {
- "value": 2,
- "name": "Very Fast"
}
}
}
}Get an enumeration
| id required | string Examples:
The enumeration to retrieve. To see a list of all possible enumeration |
| includeSchema | boolean Include the schema of the enumeration. The schema will tell you which members of the enumeration (if any) are editable. |
| includePermissions | boolean Include the effective permissions the client has with respect to this enumeration. |
| Accept-Language | Array of strings Example: en-US, de-De The language to use for display text of enumeration name and members. If no language is specified the client's default language as specified in their user profile will be used. |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/enumerations/writePriorityEnumSet?includeSchema=false&includePermissions=false' \ --header 'Accept-Language: en-US, de-De'
{- "item": {
- "name": "Absent Present",
- "members": {
- "absentpresentEnumSet.0": {
- "value": 0,
- "name": "Absent"
}, - "absentpresentEnumSet.1": {
- "value": 1,
- "name": "Present"
}, - "absentpresentEnumSet.2": {
- "value": 2,
- "name": "Hold"
}
}
}
}Can be used to modify the name of the enumeration and the values of any of the member strings. Cannot be used to add/remove members.
| id required | string Example: customEnumSet30001 The enumeration to edit. |
required | object |
{- "item": {
- "name": "Speeds",
- "members": {
- "customEnumSet30001.1": {
- "name": "Medium"
}, - "customEnumSet30001.2": {
- "name": "Fast"
}
}
}
}{- "item": {
- "name": "Speeds",
- "members": {
- "customEnumSet30001.0": {
- "value": 0,
- "name": "Slow"
}, - "customEnumSet30001.1": {
- "value": 1,
- "name": "Medium"
}, - "customEnumSet30001.2": {
- "value": 2,
- "name": "Fast"
}
}
}
}Replace an enumeration with a new definition. You can not replace a two-state enumeration with a multiple-state enumeration. Nor can you replace a multiple-state enumeration with a two-state enumeration.
| id required | string Example: customEnumSet30001 The enumeration to replace |
required | object An enumeration |
{- "item": {
- "name": "Speed",
- "members": [
- "Slow",
- "Fast",
- "Very Fast"
]
}
}{- "item": {
- "name": "Speed",
- "members": {
- "customEnumSet30001.0": {
- "value": 0,
- "name": "Slow"
}, - "customEnumSet30001.1": {
- "value": 1,
- "name": "Fast"
}, - "customEnumSet30001.2": {
- "value": 2,
- "name": "Very Fast"
}
}
}
}Delete an enumeration. Only custom enumerations may be deleted.
| id required | string Example: customEnumSet30001 The enumeration to delete. |
curl --request DELETE \ --url https:///%7Bhostname%7D/api/v5/enumerations/customEnumSet30001 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This section describes the operations you can perform on equipment. Equipment is a broad term for anything that makes a building run, including boilers, chillers, air handling units, lights, meters, and security systems. Use equipment operations to get equipment instances and to list equipment points. Apply filters, sorting, and paging to further refine the results.
Retrieves the collection of equipment instances hosted by the specified network device or its children. A network device is considered to host an equipment if the equipment defines points that map to an attribute of any object contained on the network device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/equipment?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of equipment instances.
{- "total": 1,
- "items": [
- {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.AHU-1",
- "name": "AHU-1",
- "type": "MASP AHUs",
- "upstreamEquipmentUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/upstreamEquipment",
- "networkDevicesUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices",
}
], - "next": null,
- "previous": null,
}Retrieves a collection of equipment instances.
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/equipment?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of equipment instances.
{- "total": 1,
- "items": [
- {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.AHU-1",
- "name": "AHU-1",
- "type": "MASP AHUs",
- "upstreamEquipmentUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/upstreamEquipment",
- "networkDevicesUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices",
}
], - "next": null,
- "previous": null,
}Retrieves the specified equipment instance.
| equipmentId required | string Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0 The identifier of the equipment instance. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A single equipment instance.
{- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.AHU-1",
- "name": "AHU-1",
- "type": "MASP AHUs",
- "upstreamEquipmentUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/upstreamEquipment",
- "networkDevicesUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices",
}Retrieves the equipment served by the specified equipment instance.
| equipmentId required | string Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0 The identifier of the equipment instance. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/equipment?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of equipment instances.
{- "total": 1,
- "items": [
- {
- "id": "04d68394-3415-4813-b5ec-43d840deee38",
- "itemReference": "{hostname}:{deviceHostname}/equipment.VAV-1",
- "name": "VAV-1",
- "type": "VAV Boxes",
- "upstreamEquipmentUrl": "https://{hostname}/api/v5/equipment/04d68394-3415-4813-b5ec-43d840deee38/upstreamEquipment",
- "networkDevicesUrl": "https://{hostname}/api/v5/equipment/04d68394-3415-4813-b5ec-43d840deee38/networkDevices",
}
], - "next": null,
- "previous": null,
}Retrieves the collection of equipment that serve the specified equipment instance.
| equipmentId required | string Example: 04d68394-3415-4813-b5ec-43d840deee38 The identifier of the equipment instance. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/equipment/04d68394-3415-4813-b5ec-43d840deee38/upstreamEquipment?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of equipment instances.
{- "total": 1,
- "items": [
- {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.AHU-1",
- "name": "AHU-1",
- "type": "MASP AHUs",
- "upstreamEquipmentUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/upstreamEquipment",
- "networkDevicesUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices",
}
], - "next": null,
- "previous": null,
}Retrieves the collection of points that are defined by the specified equipment instance. Each point contains a mapping to an attribute on an object.
| equipmentId required | string Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0 The identifier of the equipment instance. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "shortName" Enum: "category" "-category" "equipmentName" "-equipmentName" "isDisplayData" "-isDisplayData" "shortName" "-shortName" Example: sort=shortName The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/points?page=1&pageSize=100&sort=shortName' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of equipment points
{- "total": 31,
- "next": null,
- "previous": null,
- "items": [
- {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLG-MAXFLOW",
- "label": "Cooling Max Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLG-MINFLOW",
- "label": "Cooling Min Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLG-O",
- "label": "Cooling Output",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLGOCC-MINFLOW",
- "label": "Occ Cooling Min Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLGOCC-SP",
- "label": "Cooling Occupied Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLGUNOCC-MINFLOW",
- "label": "Unocc Cooling Min Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "CLGUNOCC-SP",
- "label": "Cooling Unoccupied Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "DA-VP",
- "label": "Discharge Air Velocity Pressure",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "DPR-O",
- "label": "Supply Air Damper Output",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "EFFCLG-SP",
- "label": "Effective Cooling Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "EFFHTG-SP",
- "label": "Effective Heating Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "EFF-OCC",
- "label": "Effective Occupancy State",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "HTG-MINFLOW",
- "label": "Heating Min Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "HTGOCC-MINFLOW",
- "label": "Occ Heating Min Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "HTGOCC-SP",
- "label": "Heating Occupied Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "HTGUNOCC-MINFLOW",
- "label": "Unocc Heating Min Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "HTGUNOCC-SP",
- "label": "Heating Unoccupied Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "OCC-MODE",
- "label": "Occupancy Status Display",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "OCC-SCHEDULE",
- "label": "Occupancy Schedule",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "SA-F",
- "label": "Supply Air Flow",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "SAFLOW-SP",
- "label": "Flow Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "SA-T",
- "label": "Supply Air Temperature",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "SYSTEM-MODE",
- "label": "System Mode",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "UNITEN-MODE",
- "label": "Unit Enable Mode",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "WC-ADJ",
- "label": "Warmer/Cooler Adjust",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "WC-C",
- "label": "WarmupCooldown",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "ZN-SP",
- "label": "Zone Setpoint",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "ZN-T",
- "label": "Zone Temperature",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "ZN-TOCC",
- "label": "Zone Temporary Occupancy",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "ZN-TOCC",
- "label": "Zone Temporary Occupancy",
- "category": "",
- "isDisplayData": false,
- "attribute": "attributeEnumSet.presentValue"
}, - {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "ZNT-STATE",
- "label": "Zone Status",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}
],
}Retrieves the collection of equipment that serve the specified space.
| spaceId required | string Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 The identifier of a space. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/equipment?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of equipment instances.
{- "total": 1,
- "items": [
- {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.AHU-1",
- "name": "AHU-1",
- "type": "MASP AHUs",
- "upstreamEquipmentUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/upstreamEquipment",
- "networkDevicesUrl": "https://{hostname}/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices",
}
], - "next": null,
- "previous": null,
}This section describes the operations you can perform on network devices. Network devices are physical devices such as coordinators and routers that are required for communication between hardware on a computer network. Use network device operations to get, list, and delete network devices. Apply filters, sorting, and paging to further refine the results.
Retrieves a collection of network devices.
| objectType | string Example: objectType=bacnetIntegrationClass metasysType: enum metasysEnum: objectTypeEnumSet The type of network device to return. The The acceptable values for this parameter come from the See also:
|
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
| classification | Array of strings Items Enum: "device" "integration" "server" "controller" Examples:
The classification to filter devices on. One or more values are supported. The |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/networkDevices?objectType=bacnetIntegrationClass&page=1&pageSize=100&sort=name&classification=device&classification=server&classification=controller' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of network devices.
{- "total": 1,
- "items": [
- {
- "id": "33b9d23d-198c-414a-980b-1ff1dca1d7ce",
- "itemReference": "{hostname}:{deviceHostname}",
- "name": "My Site Director",
- "objectType": "objectTypeEnumSet.oasClass",
- "description": "",
- "firmwareVersion": "12.0.0.0",
- "objectCategory": "objectCategoryEnumSet.systemCategory",
- "timeZone": "timeZoneEnumSet.centralTime",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/networkDevices",
- "trendedAttributesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/trendedAttributes",
- "ipAddress": "192.168.0.1",
- "certificateExpirationDate": "2023-10-27T13:11:35.0000000Z",
- "pairing": {
- "supported": true,
- "paired": false
}
}
], - "next": null,
- "previous": null,
- "effectivePermissions": {
- "canDelete": [ ],
- "canView": [
- "33b9d23d-198c-414a-980b-1ff1dca1d7ce"
], - "canModify": [
- "33b9d23d-198c-414a-980b-1ff1dca1d7ce"
]
}
}Retrieves the specified network device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A single network device.
{- "id": "33b9d23d-198c-414a-980b-1ff1dca1d7ce",
- "itemReference": "{hostname}:{deviceHostname}",
- "name": "My Site Director",
- "objectType": "objectTypeEnumSet.oasClass",
- "description": "",
- "firmwareVersion": "12.0.0.0",
- "objectCategory": "objectCategoryEnumSet.systemCategory",
- "timeZone": "timeZoneEnumSet.centralTime",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/networkDevices",
- "trendedAttributesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/trendedAttributes",
- "ipAddress": "192.168.0.1",
- "certificateExpirationDate": "2023-10-27T13:11:35.0000000Z",
- "pairing": {
- "supported": true,
- "paired": false
}
}Deletes an engine or a server which is a child device of the site director. Cannot be used to delete controllers, integrations, or the site director.
Note: The device must be offline for the operation to succeed.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
curl --request DELETE \ --url https:///%7Bhostname%7D/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Retrieves the collection of network devices that are children of the specified network device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/networkDevices?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of network devices.
{- "total": 1,
- "items": [
- {
- "id": "88cc68b1-ddaf-48c9-b15e-6ea112be848f",
- "itemReference": "{hostname}:{deviceHostname}",
- "name": "My Engine",
- "objectType": "objectTypeEnumSet.oasClass",
- "description": "",
- "firmwareVersion": "12.0.0.0",
- "objectCategory": "objectCategoryEnumSet.systemCategory",
- "timeZone": "timeZoneEnumSet.centralTime",
- "networkDevicesUrl": "https://{hostname}/api/v5/networkDevices/88cc68b1-ddaf-48c9-b15e-6ea112be848f/networkDevices",
- "trendedAttributesUrl": "https://{hostname}/api/v5/networkDevices/88cc68b1-ddaf-48c9-b15e-6ea112be848f/trendedAttributes",
- "ipAddress": "192.168.0.2",
- "certificateExpirationDate": null,
- "pairing": {
- "supported": true,
- "paired": false
}
}
], - "next": null,
- "previous": null,
- "effectivePermissions": {
- "canDelete": [ ],
- "canView": [
- "88cc68b1-ddaf-48c9-b15e-6ea112be848f"
], - "canModify": [
- "88cc68b1-ddaf-48c9-b15e-6ea112be848f"
]
}
}Allows for batching multiple requests to many network devices.
The following operations relative to a network device are supported:
| Relative Path | GET |
POST |
PUT |
PATCH |
DELETE |
|---|---|---|---|---|---|
{networkDeviceId}/certificates/bacnet |
✔ | ✔ | ❌ | ❌ | ✔ |
{networkDeviceId}/signingRequests/bacnet |
✔ | ✔ | ✔ | ❌ | ✔ |
This batch operation supports up to 1000 requests at a time.
The certificate signing request body in responses is base64 encoded PEM
content, which is different from the non-batch PEM response.
The schema of the request body is inconsistent with other batch paths. See GIV-108568.
A collection of individual requests relative to the networkDevices path. All requests will use the same HTTP method and should be for the same resource type relative to the network device.
object or string An optional shared body for all requests. This will be ignored for any individual request which defines its own | |
required | Array of objects non-empty An array of individual requests. |
Create certificate signing requests for multiple devices with the same parameters.
{- "body": {
- "city": "Milwaukee",
- "country": "US",
- "emailAddress": "noreply@jci.com",
- "orgName": "Johnson Controls",
- "orgUnitName": "BAS",
- "stateProvince": "WI"
}, - "requests": [
- {
- "id": "1",
- "method": "POST",
}, - {
- "id": "2",
- "method": "POST",
}
]
}Create certificate signing requests for multiple devices with the same parameters.
{- "responses": [
- {
- "id": "1",
- "status": 201,
- "headers": {
- "eTag": "2w6Fdcn6PJ9jrCl5Mo5fS5Vq6oVMjZc+ejN5QlFFdy8=",
- "last-modified": "Tue, 17 Aug 2021 18:36:05 GMT"
}, - "body": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQlRUQ0I5QUlCQWpDQmtURUxNQWtHQTFVRUJoTUNWVk14Q3pBSkJnTlZCQWdNQWxkSk1SSXdFQVlEVlFRSApEQWxOYVd4M1lYVnJaV1V4R1RBWEJnTlZCQW9NRUVwdmFHNXpiMjRnUTI5dWRISnZiSE14RERBS0JnTlZCQXNNCkEwSkJVekVZTUJZR0ExVUVBd3dQVFVGRE1ESTBNakJFTWprd05qVXlNUjR3SEFZSktvWklodmNOQVFrQkZnOXUKYjNKbGNHeDVRR3BqYVM1amIyMHdXVEFUQmdjcWhrak9QUUlCQmdncWhrak9QUU1CQndOQ0FBUTN4TUtOejVRMwozTVJ2YUpOaUIraEYza21UODljRE5qK01OUndac2FOSTBtNktWTkhveEZ5N25sTEVwUFlURjlQdmR6VVZrYjZiCmR4VWppalp2aWVEY29BQXdDZ1lJS29aSXpqMEVBd0lEU0FBd1JRSWdERVNSblFjN1NVcWtSRVBxdGxaSzhRWE8KY1Ivd2JpbzB0OEdmY3RLZEwzMENJUURmS3IrcHp0S0VYWUtEZ0J6UHl4SVZoa1pkb0YrTnk0aCtVdi9XUWNtRwpJZz09Ci0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo="
}, - {
- "id": "2",
- "status": 201,
- "headers": {
- "eTag": "Ugvge9WTeytxKZsUEQzsuQPX4gXvDpysa/m0NtMLnRE=",
- "last-modified": "Tue, 17 Aug 2021 18:36:05 GMT"
}, - "body": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQlRqQ0I5QUlCQWpDQmtURUxNQWtHQTFVRUJoTUNWVk14Q3pBSkJnTlZCQWdNQWxkSk1SSXdFQVlEVlFRSApEQWxOYVd4M1lYVnJaV1V4R1RBWEJnTlZCQW9NRUVwdmFHNXpiMjRnUTI5dWRISnZiSE14RERBS0JnTlZCQXNNCkEwSkJVekVZTUJZR0ExVUVBd3dQVFVGRE1ESTBNamN3TXpWQlF6WkVNUjR3SEFZSktvWklodmNOQVFrQkZnOXUKYjNKbGNHeDVRR3BqYVM1amIyMHdXVEFUQmdjcWhrak9QUUlCQmdncWhrak9QUU1CQndOQ0FBUTdiWExaNDZQeQpSaTc5Tlpka2REWko3SitFUnRZMVRqT0QrWDYra1VrYlQ2TElBRnZncjJxL25GOEo1eHRsSXM2bGJPOXY3T29vCklFRmhKN0tMa2NaR29BQXdDZ1lJS29aSXpqMEVBd0lEU1FBd1JnSWhBT0VDbjJaNDhnZzNFRmJtdXpMU0NXWkQKNEUyaEw0d1ZhRmpZMkNmdTdGdWFBaUVBOGphUVc3Z0ZxZjVWNS83WkFiL2RVQnZScXBWQVFYNERHTlBkNnEwbQp1d0U9Ci0tLS0tRU5EIENFUlRJRklDQVRFIFJFUVVFU1QtLS0tLQo="
}
]
}Retrieves the collection of network devices that host the specified equipment instance, along with the parents of those network devices. A network device hosts an equipment when the equipment defines points that map to an attribute of any object contained on the network device.
| equipmentId required | string Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0 The identifier of the equipment instance. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of network devices.
{- "total": 1,
- "items": [
- {
- "id": "33b9d23d-198c-414a-980b-1ff1dca1d7ce",
- "itemReference": "{hostname}:{deviceHostname}",
- "name": "My Site Director",
- "objectType": "objectTypeEnumSet.oasClass",
- "description": "",
- "firmwareVersion": "12.0.0.0",
- "objectCategory": "objectCategoryEnumSet.systemCategory",
- "timeZone": "timeZoneEnumSet.centralTime",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/networkDevices",
- "trendedAttributesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/trendedAttributes",
- "ipAddress": "192.168.0.1",
- "certificateExpirationDate": "2023-10-27T13:11:35.0000000Z",
- "pairing": {
- "supported": true,
- "paired": false
}
}
], - "next": null,
- "previous": null,
- "effectivePermissions": {
- "canDelete": [ ],
- "canView": [
- "33b9d23d-198c-414a-980b-1ff1dca1d7ce"
], - "canModify": [
- "33b9d23d-198c-414a-980b-1ff1dca1d7ce"
]
}
}Retrieves the collection of network devices that serve the specified space. A space serves a network device when any equipment instance serving the space defines points that map to an attribute of any object contained on the network device.
| spaceId required | string Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 The identifier of a space. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of network devices.
{- "total": 1,
- "items": [
- {
- "id": "33b9d23d-198c-414a-980b-1ff1dca1d7ce",
- "itemReference": "{hostname}:{deviceHostname}",
- "name": "My Site Director",
- "objectType": "objectTypeEnumSet.oasClass",
- "description": "",
- "firmwareVersion": "12.0.0.0",
- "objectCategory": "objectCategoryEnumSet.systemCategory",
- "timeZone": "timeZoneEnumSet.centralTime",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/networkDevices",
- "trendedAttributesUrl": "https://{hostname}/api/v5/networkDevices/33b9d23d-198c-414a-980b-1ff1dca1d7ce/trendedAttributes",
- "ipAddress": "192.168.0.1",
- "certificateExpirationDate": "2023-10-27T13:11:35.0000000Z",
- "pairing": {
- "supported": true,
- "paired": false
}
}
], - "next": null,
- "previous": null,
- "effectivePermissions": {
- "canDelete": [ ],
- "canView": [
- "33b9d23d-198c-414a-980b-1ff1dca1d7ce"
], - "canModify": [
- "33b9d23d-198c-414a-980b-1ff1dca1d7ce"
]
}
}Retrieves a list of objects for the well known alarm query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/alarm?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that are in alarm for the device. The object id needs to be a supervisory device.
{- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/AV1",
- "name": "AV1",
- "description": "AV1",
- "objectType": "objectTypeEnumSet.avClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osLowAlarm",
- "value": {
- "item": 70.1965561,
- "schema": {
- "type": "number",
- "metasysType": "float",
- "units": {
- "id": "unitEnumSet.degF",
- "title": "deg F"
}, - "unitsSource": "attributeEnumSet.units",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "displayPrecisionSource": "attributeEnumSet.displayPrecision"
}
}
}, - {
- "id": "187d032d-6156-5d9f-bfe8-c2a14d5c22df",
- "itemReference": "{hostname}:{deviceHostname}/SF-S",
- "name": "Supply Fan Status",
- "description": "Supply Fan Status",
- "objectType": "objectTypeEnumSet.mvClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osAlarm",
- "value": {
- "item": "offonEnumSet.0",
- "schema": {
- "type": "string",
- "metasysType": "enum",
- "enumSetSource": "attributeEnumSet.statesText",
}
}
}
]
}Retrieves a list of objects for the well known disabled query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/disabled?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that are disabled.
{- "next": null,
- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/ZN-T.Trend1",
- "name": "Trend - Present Value",
- "description": null,
- "objectType": "objectTypeEnumSet.trendLogClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osDisabled"
}
]
}Retrieves a list of objects for the well known offline query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/offline?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that are offline.
{- "next": null,
- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/MSTP.FEC1.ZN-T",
- "name": "ZN-T",
- "description": "ZN-T",
- "objectType": "objectTypeEnumSet.bacAiClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osOffline"
}
]
}Retrieves a list of objects for the well known operator override query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/operatorOverride?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that are in operator override.
{- "next": null,
- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/MSTP.FEC1.RA-T",
- "name": "RA-T",
- "description": "RA-T",
- "objectType": "objectTypeEnumSet.bacAiClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osOperatorOverride",
- "value": {
- "item": 70.1965561,
- "schema": {
- "type": "number",
- "metasysType": "float",
- "units": {
- "id": "unitEnumSet.degF",
- "title": "deg F"
}, - "unitsSource": "attributeEnumSet.units",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "displayPrecisionEnumSet": "attributeEnumSet.displayPrecision"
}
}
}
]
}Retrieves a list of objects for the well known out of service query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/outOfService?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that are out of service.
{- "next": null,
- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/MSTP.FEC1.ZN-T",
- "name": "ZN-T",
- "description": "ZN-T",
- "objectType": "objectTypeEnumSet.bacAiClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osOutOfService"
}
]
}Retrieves a list of objects for the well known supervisory override query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/supervisoryOverride?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that are in supervisory override.
{- "next": null,
- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/MSTP.FEC1.ZN-T",
- "name": "ZN-T",
- "description": "ZN-T",
- "objectType": "objectTypeEnumSet.bacAiClass",
- "deviceName": "Building 1 NAE",
- "status": "objectStatusEnumSet.osOperatorOverride",
- "value": {
- "item": 70.1965561,
- "schema": {
- "type": "number",
- "metasysType": "float",
- "units": {
- "id": "unitEnumSet.degF",
- "title": "deg F"
}, - "unitsSource": "attributeEnumSet.units",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "displayPrecisionEnumSet": "attributeEnumSet.displayPrecision"
}
}
}
]
}Retrieves a list of objects for the well known trouble query.
| objectId required | string Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008 The identifier of the object. This must be a supervisory device object id for a well known query. |
| cursor | integer Example: cursor=243 A handle to next page of data |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/trouble?cursor=243&pageSize=100' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get all of the objects that have a trouble status.
{- "next": null,
- "items": [
- {
- "id": "07cece90-d0fd-518a-b7fe-38503d45c1a9",
- "itemReference": "{hostname}:{deviceHostname}/MSTP.FEC1.ZN-T",
- "name": "ZN-T",
- "description": "ZN-T",
- "objectType": "objectTypeEnumSet.bacAiClass",
- "deviceName": "Building 1 NAE"
}
]
}This section describes the operations you can perform on objects. Objects are self-contained functional items in the Metasys system, for a full definition refer to the Metasys System Glossary. Some operations accept subscriptions, see Change of Value Subscriptions.
(INTERNAL) Some operations have limitations, see Operation Restrictions.
Use change of value subscription to receive updates when attribute values change. Currently, subscriptions are only available for Get attribute value operations (individual and batch).
To subscribe to a change of value subscription, complete the following steps:
There are three event types sent by the attribute subscription: heartbeat, update, and notification.
object.values.heartbeat - A heartbeat event is sent every 30 seconds to tell
you the subscription is still alive. It is a JSON string with the current UTC
date time in ISO 8601 format.
"2021-09-16T19:58:28.5902588Z"
object.values.update - An update event is sent when an attribute value
changes and the value is included in the event. Here is an example data
payload for this type of event. This payload is the same as the payload
returned by Get attribute value, except for the inclusion of id and
itemReference in the item object. The overall schema for this payload is
identical to the Get an object schema (except this payload has no schema
or effectivePermissions properties).
{
"item": {
"presentValue": 76.5,
"id": "960534d2-7df5-5ed8-884c-164e7a2f280a",
"itemReference": "{hostname}:{deviceHostname}/AV1"
},
"condition": {
"presentValue": {
"reliability": "reliabilityEnumSet.reliable",
"priority": "writePriorityEnumSet.priorityDefault"
}
}
}
object.values.notification - The notification event is sent when a value has
changed but the value is not included in the payload. This happens for some
values that are not simple scalar values. You can use this event as a trigger
to reread the attribute.
In the following example, even though the payload does not include the current
value, you know which object this is for (based on id and itemReference),
and you know it is the overrideExpirationTime attribute based on the
attribute property.
{
"item": {
"id": "960534d2-7df5-5ed8-884c-164e7a2f280a",
"itemReference": "{hostname}:{deviceHostname}/AV1"
},
"condition": {
"overrideExpirationTime": {
"reliability": "reliabilityEnumSet.reliable",
"priority": "writePriorityEnumSet.priorityNone"
}
},
"attribute": "attributeEnumSet.overrideExpirationTime"
}
To unsubscribe from a change of value subscription, complete the following steps:
METASYS-SUBSCRIPTION-LOCATION from the subscribe operation
response.METASYS-SUBSCRIPTION-LOCATION.There are restrictions on certain operations that are not otherwise communicated by the API. These are documented in the following requirements and restrict the creation of certain objects and the writing of certain attributes.
| Object Type | Forbidden Create | Forbidden Attribute Writes |
|---|---|---|
| Interlock | [G4R-4055][] | [G4R-4054][] - actionTbl1, actionTbl2, commandsPriority, source |
| MCO | [G4R-4057][] | [G4R-4056][] - actionTbl1, commandsPriority |
| DLLR | n/a | [G4R-4053][] - loadList |
| System | n/a | [G4R-4060][] - attributeInfo, fileName, logicSequence |
The attributes of the System object should be marked readOnly in the schema
and a CR (G4CR-8324) is written up for that. The other restrictions are
intended to be removed in a future release.
Returns the root object of the tree and, optionally, its children. The root
object is the site object. The default response is a tree representation.
Set flatten=true to flatten the tree into a list representation. The
number of levels returned depends on the value of the depth parameter. To
get just the root of the tree use a depth of 0. Values of depth greater
than 1 are not allowed on this endpoint.
| depth | integer [ 0 .. 1 ] Default: 1 Example: depth=1 The depth of the tree to return. The provided value is ignored if |
| flatten | boolean Default: false A value of |
| includeExtensions | boolean Default: false A value of This parameter is ignored if |
| pathTo | string Example: pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a This parameter causes the response to contain the object specified by this parameter, the root object, and the objects in between. If this parameter is specified, then |
| includeInternal | boolean Default: false visibility: internal (INTERNAL) A value of |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects?depth=1&flatten=false&includeExtensions=false&pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a&includeInternal=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The objects are returned in a tree structure. Child objects are nested under their parents.
{- "items": [
- {
- "parentUrl": null,
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/29f2ab56-5f52-55b6-bfb7-10328d79bc81/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}/$site",
- "hasChildrenMatchingQuery": true,
- "name": "Site",
- "id": "29f2ab56-5f52-55b6-bfb7-10328d79bc81",
- "objectType": "objectTypeEnumSet.siteClass",
- "classification": "site",
- "items": [
- {
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/851bf2f5-1043-5418-873a-182f0daa047f/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}/$site.UserTrees",
- "hasChildrenMatchingQuery": false,
- "name": "User Views",
- "id": "851bf2f5-1043-5418-873a-182f0daa047f",
- "objectType": "objectTypeEnumSet.containerClass",
- "classification": "folder",
- "items": [ ]
}, - {
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/727072c8-bc67-5f38-8623-485a9d73af4f/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}/$site.SummaryDefs",
- "hasChildrenMatchingQuery": false,
- "name": "Summary Definitions",
- "id": "727072c8-bc67-5f38-8623-485a9d73af4f",
- "objectType": "objectTypeEnumSet.containerClass",
- "classification": "folder",
- "items": [ ]
}, - {
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/8db194bc-68ee-599f-952e-983a7b86c456/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}",
- "hasChildrenMatchingQuery": true,
- "name": "{hostname}",
- "id": "8db194bc-68ee-599f-952e-983a7b86c456",
- "objectType": "objectTypeEnumSet.oasClass",
- "classification": "server",
- "items": [ ]
}
]
}
]
}Creates a new object. Several things are needed to successfully create an object. You must know
Find the complete list of object types with the operation
GET /schemas/enums/objectTypeEnumSet. To determine the specific set of
objects that can be created in a location use List supported child types
(GET /objects/{objectId}/supportedChildTypes). To discover what object
properties can be set and which are required when creating an object use
Get a schema for an object type (GET /schemas/objectTypes/{objectType})
See also:
objectTypeEnumSet enumeration.| parentId required | string The ID of the parent object. The new object will be created under this object. |
| localUniqueIdentifier required | string A string that is locally unique within the context of the parent object
for identifying the new object. This string will be the last component of
the |
| objectType required | string metasysType: enum metasysEnum: objectTypeEnumSet The type of object to create. The values for this property come from the See also:
|
| item | object The This property may or may not be required depending on the object you are creating. Some objects have defaults for all properties and require nothing to be set when creating them. Others have required properties that must be set at creation time. |
This request body creates a new object of type objectTypeEnumSet.avClass under a folder with an identifier of 82b6f2d5-6fed-5074-b611-94dd40028312 with a locally unique identifier of ZN-3-SETPT. The properties on the new object are name, description, objectCategory, minPresValue and maxPresValue.
{- "parentId": "82b6f2d5-6fed-5074-b611-94dd40028312",
- "localUniqueIdentifier": "ZN-3-SETPT",
- "objectType": "objectTypeEnumSet.avClass",
- "item": {
- "name": "Zone 3 Setpoint",
- "description": "Zone 3 Temperature Setpoint",
- "objectCategory": "objectCategoryEnumSet.hvacCategory",
- "minPresValue": 55,
- "maxPresValue": 95
}
}Returns the specified object and optionally one or more levels of the tree
under the object. The default response is a tree representation. Set
flatten=true to flatten the tree into a list representation.
| objectId required | string Example: 767d8af0-163f-552c-ba37-a884466075f9 Specifies the root of the subtree to return for this request. The |
| depth | integer >= -1 Default: 1 Example: depth=1 The depth of the tree to return. For typical usage, a value or 1 or 2 is
recommended. Use The provided value is ignored if |
| flatten | boolean Default: false A value of |
| includeExtensions | boolean Default: false A value of This parameter is ignored if |
| pathTo | string Example: pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a This parameter filters the response down to just containing the object
specified by this parameter, the object specified by If this parameter is specified, then |
| objectType | string Examples:
metasysType: enum metasysEnum: objectTypeEnumSet Type of objects to include in the response. This parameter may be
repeated. To search for all AV and AI objects one would specify
The use of this parameter overrides It is an error to specify this parameter if The response will include the specified object, the objects that match
the The acceptable values for this parameter come from the See also:
|
| classification | string Enum: "object" "device" "integration" "controller" "point" "site" "navList" "extension" "folder" "reference" "server" "archive" Examples:
Filter objects to those with the specific classification. The use of this parameter overrides |
| includeInternal | boolean Default: false visibility: internal (INTERNAL) A value of |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/767d8af0-163f-552c-ba37-a884466075f9/objects?depth=1&flatten=false&includeExtensions=false&pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a&objectType=objectTypeEnumSet.avClass&classification=object&includeInternal=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The objects are returned in a tree structure. Child objects are nested under their parents.
{- "items": [
- {
- "parentUrl": null,
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/29f2ab56-5f52-55b6-bfb7-10328d79bc81/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}/$site",
- "hasChildrenMatchingQuery": true,
- "name": "Site",
- "id": "29f2ab56-5f52-55b6-bfb7-10328d79bc81",
- "objectType": "objectTypeEnumSet.siteClass",
- "classification": "site",
- "items": [
- {
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/851bf2f5-1043-5418-873a-182f0daa047f/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}/$site.UserTrees",
- "hasChildrenMatchingQuery": false,
- "name": "User Views",
- "id": "851bf2f5-1043-5418-873a-182f0daa047f",
- "objectType": "objectTypeEnumSet.containerClass",
- "classification": "folder",
- "items": [ ]
}, - {
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/727072c8-bc67-5f38-8623-485a9d73af4f/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}/$site.SummaryDefs",
- "hasChildrenMatchingQuery": false,
- "name": "Summary Definitions",
- "id": "727072c8-bc67-5f38-8623-485a9d73af4f",
- "objectType": "objectTypeEnumSet.containerClass",
- "classification": "folder",
- "items": [ ]
}, - {
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/8db194bc-68ee-599f-952e-983a7b86c456/trendedAttributes",
- "itemReference": "{hostname}:{deviceHostname}",
- "hasChildrenMatchingQuery": true,
- "name": "{hostname}",
- "id": "8db194bc-68ee-599f-952e-983a7b86c456",
- "objectType": "objectTypeEnumSet.oasClass",
- "classification": "server",
- "items": [ ]
}
]
}
]
}(NOT IMPLEMENTED) This is a design for an operation not yet implemented.
This endpoint changes the ordering of objects under a specified object.
This is an asynchronous operation which must be invoked with a valid
METASYS-SUBSCRIBE header (obtained by using the Get a stream operation).
If the request was valid, then when the operation completes an
objects.ordering.update event will be sent over the stream.
The data payload within the event includes the resulting ordering. If the
resulting ordering matches the requested ordering then the payload will
include a status property with the value statusEnumSet.ok, otherwise the
status will indicate an error:
statusEnumSet.operationCompletionError - There was an error updating the
ordering.statusEnumSet.deviceOffline - The update could not happen because the
device was offline.{
"self": "https://{hostname}/api/v5/objects/767d8af0-163f-552c-ba37-a884466075f9/objects/ordering",
"parentId": "767d8af0-163f-552c-ba37-a884466075f9"
"status": "statusEnumSet.ok",
"items": [
"2312c7e2-332f-55b1-a700-cf292fb5d815",
"7ca7fddf-0d54-53a0-b94c-f9a2a5f38e0b",
"dcb93e5b-4395-53f2-aa8b-8f95dcc757f8",
"597b3cec-e452-5032-92fb-bcf837a65250"
],
"subscriptionIds": ["538f00be-5788-4f68-a60e-45a14356c7ef"]
}
The items collection will be null if the device is offline or for some
reason the current ordering could not be determined.
Implementation details: If one or more object writes fail resulting in an ordering that does not match the requested ordering, then the status shall be
statusEnumSet.operationCompletionError. If one or more writes fail but the resulting ordering does match the requested ordering the status should bestatusEnumSet.ok. How might this happen? Assume I have the ordering[a, b, c, d]and I request to change it to[a, b, d, c]. I assume we attempt to write each object. Now if the writes toaandbfail, presumably that's fine since their values aren't changing. Note: Since this seems extremely unlikely (the only scenario we are aware where this would fail is when the device is offline) I'm okay with skipping the check in first implementation.
See also:
| objectId required | string Example: 767d8af0-163f-552c-ba37-a884466075f9 Specifies a parent object. |
| METASYS-SUBSCRIBE required | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b The value of this header is a stream id obtained by opening a stream with Get a stream. A response from the operation will be sent over the stream when it is ready. See also: |
| items required | Array of strings An array of object identifiers. Each entry is an identifier of one of the child objects. The order of the identifiers in the array shall indicate the new ordering of the child objects. It is acceptable to send an array of identifiers that is a subset of all of the child object identifiers. In that case, the specified identifiers shall be ordered first. The identifiers that are not included in the request will maintain their relative order with respect to each other but shall come after all of the specified identifiers. For example, if the current ordering is |
{- "items": [
- "597b3cec-e452-5032-92fb-bcf837a65250",
- "7ca7fddf-0d54-53a0-b94c-f9a2a5f38e0b",
- "dcb93e5b-4395-53f2-aa8b-8f95dcc757f8",
- "2312c7e2-332f-55b1-a700-cf292fb5d815"
]
}Finds the object identifier (the id property of an object) for the object with the specified fully qualified reference (fqr).
| fqr required | string Examples:
format: fully-qualified-reference The fully qualified reference of an object. Fully qualified references use characters that must be escaped when used
as query parameters. Most HTTP libraries do this for you automatically.
However, if you are using |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objectIdentifiers?fqr=adx%3Aadx' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
"32cfddc0-411f-5b9e-9a6d-442cb62fecbb"Objects support one or more views. By default, this operation gets the
default view of an object. For many objects this is the Focus View
(identifier viewNameEnumSet.focusView). To see the list of views an object
supports see List Views (/objects/{objectId}/views). To get a different
view of an object specify a value for the viewId parameter.
Licensing Restrictions
Requires Monitoring and Commanding API license.
See also:
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| viewId | string Examples:
metasysEnum: viewNameEnumSet The view to retrieve. This parameter is optional and if it is not specified the default view
for the object will be returned. For many objects this is the Focus view
( The acceptable values for this parameter come from the See also:
|
| includeSchema | boolean Every object can have a unique schema. Set this parameter to |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb?viewId=viewNameEnumSet.focusView&includeSchema=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This is an example of an AV object without a schema. Notice that the
presentValue is 105 but the maxPresValue is set to 100. This results
in the presentValue attribute going unreliable. This can be seen in the
condition object where presentValue has a reliability value of
reliabilityEnumSet.unreliableHigh. We can also see that the current
priority for presentValue is set to
writePriorityEnumSet.priorityCriticalEquipment.
{- "objectType": "objectTypeEnumSet.avClass",
- "networkDeviceUrl": "https://{hostname}/api/v5/networkDevices/8f2c6bb1-6bfd-5643-b581-299c1fec6b1b",
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/ce820989-5617-50bd-90ea-2fd95d1402ba/trendedAttributes",
- "item": {
- "name": "AV1",
- "description": null,
- "bacnetObjectType": "objectTypeEnumSet.bacAvClass",
- "objectCategory": "objectCategoryEnumSet.generalCategory",
- "outOfService": false,
- "reliability": "reliabilityEnumSet.unreliableHigh",
- "currentCommandPriority": 5,
- "alarmState": "objectStatusEnumSet.osNormal",
- "overrideExpirationTime": {
- "date": null,
- "time": null
}, - "presentValueWritable": "objectModeEnumSet.presentValueWritableWithPriority",
- "itemReference": "{hostname}:{deviceHostname}/Programming.AV1",
- "version": {
- "major": 1,
- "minor": 0
}, - "prioritySupported": true,
- "minPresValue": -1.6999999760721821e+38,
- "maxPresValue": 100,
- "units": "unitEnumSet.noUnits",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1",
- "covIncrement": 0.01,
- "connectedToInternalApplication": "noYesEnumSet.fanNo",
- "presentValue": 105,
- "status": "objectStatusEnumSet.osHighPriority",
- "attrChangeCount": 9,
- "defaultAttribute": "attributeEnumSet.presentValue",
- "id": "ce820989-5617-50bd-90ea-2fd95d1402ba"
}, - "effectivePermissions": {
- "canDelete": true,
- "canModify": true
}, - "views": [
- {
- "title": "Focus",
- "views": [
- {
- "title": "Basic",
- "views": [
- {
- "title": "Object",
- "properties": [
- "name",
- "description",
- "bacnetObjectType",
- "objectCategory"
], - "id": "viewGroupEnumSet.objectGrp"
}, - {
- "title": "Status",
- "properties": [
- "outOfService",
- "reliability",
- "currentCommandPriority",
- "alarmState",
- "overrideExpirationTime",
- "presentValueWritable"
], - "id": "viewGroupEnumSet.statusGrp"
}
], - "id": "groupTypeEnumSet.basicGrpType"
}, - {
- "title": "Advanced",
- "views": [
- {
- "title": "Engineering Values",
- "properties": [
- "itemReference",
- "version",
- "prioritySupported",
- "minPresValue",
- "maxPresValue"
], - "id": "viewGroupEnumSet.engValuesGrp"
}, - {
- "title": "Display",
- "properties": [
- "units",
- "displayPrecision",
- "covIncrement"
], - "id": "viewGroupEnumSet.displayGrp"
}, - {
- "title": "Internal Logic Interface",
- "properties": [
- "connectedToInternalApplication"
], - "id": "viewGroupEnumSet.internalLogicIfGrp"
}
], - "id": "groupTypeEnumSet.advancedGrpType"
}, - {
- "title": "Key",
- "views": [
- {
- "title": "None",
- "properties": [
- "presentValue",
- "status",
- "attrChangeCount",
- "defaultAttribute"
], - "id": "viewGroupEnumSet.noGrp"
}
], - "id": "groupTypeEnumSet.keyGrpType"
}
], - "id": "viewNameEnumSet.focusView"
}
], - "condition": {
- "presentValue": {
- "reliability": "reliabilityEnumSet.unreliableHigh",
- "priority": "writePriorityEnumSet.priorityCriticalEquipment"
}
}
}This operation modifies one or more attributes of an object. Note:
attributes must be updated in whole. For example, if you wish to modify an
attribute of metasysType struct which is modelled as a JSON object you
must include all elements of the struct. It is undefined what might happen
if you do not. The write could fail, the non-mentioned members may get their
default value or something else. This applies to any attribute that has a
JSON type of array or object. The entire attribute value must be written
even if you only wish to change one part of the value.
The request body contains an item property which contains one or more
properties and their new values.
The attributes of an object (and their schemas) can be discovered by looking at the different views of an object or by requesting all of the attributes.
Licensing Restrictions
Requires Monitoring and Commanding API license.
See also:
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| item | object The attributes to update. |
{- "item": {
- "presentValue": 71.5
}
}Deletes the specified object.
Not all objects can be deleted (not even by an administrator). Examine the
effectivePermissions of an object to determine if it can be deleted by the
current user.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request DELETE \ --url https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Objects support one or more views. Each view of an object contains a logical grouping of the object's attributes. This operation lists the collection of views that an object has.
Each entry in the response contains the id of a view, and also the
absolute URL used to request that view. Use Get an object
(/objects/{objectId}) to request a specific view by specifying the desired
id for the viewId query parameter.
See also:
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/views \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "items": [
- {
- "id": "viewNameEnumSet.focusView",
}, - {
- "id": "viewNameEnumSet.optionsView",
}
],
}Returns a set of attributes for an object. The attributes returned are considered public information for any authenticated user and therefore no special privileges are required to call this operation.
One of the attributes returned by this operation (for many objects) is the
default attribute (defaultAttribute). If the object has a default
attribute then the attribute named by the defaultAttribute property is
also included in the response. For example, the analog value (AV) object has
a defaultAttribute of attributeEnumSet.presentValue so presentValue is
included in the public view of an AV.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| includeSchema | boolean Every object can have a unique schema. Set this parameter to |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/publicView?includeSchema=false' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This is an example of a public view for an AV object with schema included.
{- "objectType": "objectTypeEnumSet.avClass",
- "networkDeviceUrl": "https://{hostname}/api/v5/networkDevices/4d762b40-b3f5-5bed-bba9-d5820993cea7",
- "trendedAttributesUrl": "https://{hostname}/api/v5/objects/960534d2-7df5-5ed8-884c-164e7a2f280a/trendedAttributes",
- "item": {
- "name": "AV1",
- "itemReference": "{hostname}:{deviceHostname}/AV1",
- "description": null,
- "objectCategory": "objectCategoryEnumSet.generalCategory",
- "status": "objectStatusEnumSet.osNormal",
- "alarmState": "objectStatusEnumSet.osNormal",
- "defaultAttribute": "attributeEnumSet.presentValue",
- "bacnetObjectType": "objectTypeEnumSet.bacAvClass",
- "overrideExpirationTime": {
- "date": null,
- "time": null
}, - "attrChangeCount": 110,
- "reliability": "reliabilityEnumSet.reliable",
- "version": {
- "major": 1,
- "minor": 0
}, - "presentValue": "0"
}, - "schema": {
- "type": "object",
- "language": "en-US",
- "title": "JCI AV",
- "version": "1.0",
- "properties": {
- "name": {
- "title": "Name",
- "category": "attributeCategoryEnumSet.nameCategory",
- "type": "string",
- "metasysType": "string"
}, - "itemReference": {
- "title": "Item Reference",
- "readOnly": true,
- "category": "attributeCategoryEnumSet.objectNameCategory",
- "type": "string",
- "metasysType": "string"
}, - "description": {
- "title": "Description",
- "oneOf": [
- {
- "type": "string"
}, - {
- "type": "null"
}
], - "metasysType": "string"
}, - "objectCategory": {
- "title": "Authorization Category",
- "category": "attributeCategoryEnumSet.objectCategoryCategory",
- "numberOfStates": 250,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#objectCategoryEnumSet"
}
]
}, - "status": {
- "title": "Status",
- "readOnly": true,
- "dynamic": true,
- "numberOfStates": 120,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#objectStatusEnumSet"
}
]
}, - "alarmState": {
- "title": "Alarm State",
- "readOnly": true,
- "dynamic": true,
- "numberOfStates": 120,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#objectStatusEnumSet"
}
]
}, - "default": {
- "title": "Default",
- "prioritized": true,
- "dynamic": true,
- "displayPrecisionSource": "displayPrecision",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "minimum": -3.40282347e+38,
- "maximum": 3.40282347e+38,
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}
}, - "defaultAttribute": {
- "title": "Default Attr Number",
- "readOnly": true,
- "oneOf": [
- {
- "type": "string"
}, - {
- "type": "null"
}, - {
- "$ref": "#attributeEnumSet"
}
], - "metasysType": "enum"
}, - "bacnetObjectType": {
- "title": "Object Type",
- "readOnly": true,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#objectTypeEnumSet"
}
]
}, - "overrideExpirationTime": {
- "title": "Override Expiration Time",
- "readOnly": true,
- "category": "attributeCategoryEnumSet.bacnetDateTimeCategory",
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "date": {
- "oneOf": [
- {
- "allOf": [
- {
- "$ref": "#metasys-date"
}, - {
- "required": [
- "year",
- "month",
- "dayOfMonth"
], - "display": [
- "year",
- "month",
- "dayOfMonth"
]
}
]
}, - {
- "type": "null"
}
], - "metasysType": "date",
- "title": "Date"
}, - "time": {
- "oneOf": [
- {
- "allOf": [
- {
- "$ref": "#metasys-time"
}, - {
- "required": [
- "hour",
- "minute",
- "second"
], - "display": [
- "hour",
- "minute",
- "second"
]
}
]
}, - {
- "type": "null"
}
], - "metasysType": "time",
- "title": "Time"
}
}
}, - "attrChangeCount": {
- "title": "Attr Change Count",
- "readOnly": true,
- "dynamic": true,
- "metasysType": "byte",
- "type": "integer",
- "minimum": 0,
- "maximum": 255
}, - "reliability": {
- "title": "Reliability",
- "numberOfStates": 116,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#reliabilityEnumSet_endAt_116"
}
]
}, - "version": {
- "title": "Version",
- "readOnly": true,
- "category": "attributeCategoryEnumSet.versionStructCategory",
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "major": {
- "metasysType": "byte",
- "type": "integer",
- "minimum": 0,
- "maximum": 255,
- "title": "Major"
}, - "minor": {
- "metasysType": "byte",
- "type": "integer",
- "minimum": 0,
- "maximum": 255,
- "title": "Minor"
}
}
}
}, - "definitions": {
- "objectCategoryEnumSet": {
- "title": "Authorization Category",
- "$id": "#objectCategoryEnumSet",
- "setId": 33
}, - "objectStatusEnumSet": {
- "title": "Object Status",
- "$id": "#objectStatusEnumSet",
- "setId": 505
}, - "attributeEnumSet": {
- "title": "Attribute",
- "$id": "#attributeEnumSet",
- "setId": 509
}, - "objectTypeEnumSet": {
- "title": "Object Type",
- "$id": "#objectTypeEnumSet",
- "setId": 508
}, - "metasys-date": {
- "$id": "#metasys-date",
- "title": "date",
- "description": "Metasys Date",
- "type": "object",
- "properties": {
- "year": {
- "type": "integer",
- "description": "Year"
}, - "month": {
- "type": "integer",
- "minimum": 1,
- "maximum": 12,
- "description": "Month"
}, - "dayOfMonth": {
- "type": "integer",
- "minimum": 1,
- "maximum": 31,
- "description": "Day of Month"
}, - "dayOfWeek": {
- "type": "integer",
- "minimum": 1,
- "maximum": 7,
- "description": "Day of Week"
}
}, - "additionalProperties": false
}, - "metasys-time": {
- "$id": "#metasys-time",
- "title": "time",
- "description": "Metasys time",
- "type": "object",
- "properties": {
- "hour": {
- "type": "integer",
- "minimum": 0,
- "maximum": 23,
- "description": "Hour"
}, - "minute": {
- "type": "integer",
- "minimum": 0,
- "maximum": 59,
- "description": "Minute"
}, - "second": {
- "type": "integer",
- "minimum": 0,
- "maximum": 59,
- "description": "Second"
}, - "hundredth": {
- "type": "integer",
- "minimum": 0,
- "maximum": 99,
- "description": "Hundredths"
}
}, - "additionalProperties": false
}, - "reliabilityEnumSet_endAt_116": {
- "title": "Reliability",
- "$id": "#reliabilityEnumSet_endAt_116",
- "setId": 503
}
}
}, - "effectivePermissions": {
- "canDelete": true,
- "canModify": true
}, - "condition": { }
}Returns an object payload with a JSON schema that contains all of the
properties of the object. Each property entry contains only a partial schema
for that property. (To discover the full schema of an attribute use
/objects/{objectId}?includeSchema=true or
/objects/{objectId}/attributes/{attrId}?includeSchema=true
The item section of the payload will contain at most one attribute, the
defaultAttribute. The item section will be completely missing if the
object does not have a default attribute.
There will be no views or condition sections like a typical object payload.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/attributes \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "item": {
- "defaultAttribute": "attributeEnumSet.presentValue"
}, - "schema": {
- "type": "object",
- "language": "en-US",
- "title": "JCI AV",
- "version": "1.0",
- "properties": {
- "presentValue": {
- "title": "Present Value",
- "prioritized": true,
- "metasysType": "float",
- "type": "number",
- "minimum": -3.40282347e+38,
- "maximum": 3.40282347e+38
}, - "reliability": {
- "title": "Reliability",
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "outOfService": {
- "title": "Out Of Service",
- "prioritized": false,
- "type": "boolean",
- "metasysType": "bool"
}, - "statusFlags": {
- "title": "Status Flags",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "bitString"
}, - "eventState": {
- "title": "Event State",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "presentValueWritable": {
- "title": "Present Value Writable",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "connectedToInternalApplication": {
- "title": "Connected to Internal Application",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "bacnetExposed": {
- "title": "BACnet Exposed",
- "prioritized": false,
- "type": "boolean",
- "metasysType": "bool"
}, - "maxPresValue": {
- "title": "Max Value",
- "prioritized": false,
- "metasysType": "float",
- "type": "number",
- "minimum": -3.40282347e+38,
- "maximum": 3.40282347e+38
}, - "minPresValue": {
- "title": "Min Value",
- "prioritized": false,
- "metasysType": "float",
- "type": "number",
- "minimum": -3.40282347e+38,
- "maximum": 3.40282347e+38
}, - "covIncrement": {
- "title": "COV Increment",
- "prioritized": false,
- "metasysType": "float",
- "type": "number",
- "minimum": -3.40282347e+38,
- "maximum": 3.40282347e+38
}, - "units": {
- "title": "Units",
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "displayPrecision": {
- "title": "Display Precision",
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "propertyRefValue": {
- "title": "Property Ref Value",
- "readOnly": true,
- "prioritized": false,
- "metasysType": "attributeReference",
- "oneOf": [
- {
- "$ref": "#attribute-reference"
}
]
}, - "connectedTo": {
- "title": "Connected To",
- "prioritized": false,
- "metasysType": "attributeReference",
- "oneOf": [
- {
- "$ref": "#attribute-reference"
}
]
}, - "connectedStatus": {
- "title": "Connected Status",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "direction": {
- "title": "Direction",
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "prioritySupported": {
- "title": "Priority Supported",
- "prioritized": false,
- "type": "boolean",
- "metasysType": "bool"
}, - "relinquishDefault": {
- "title": "Relinquish Default",
- "prioritized": false,
- "metasysType": "float",
- "type": "number",
- "minimum": -3.40282347e+38,
- "maximum": 3.40282347e+38
}, - "restoreCommandPriority": {
- "title": "Restore Command Priority",
- "prioritized": false,
- "type": "string",
- "metasysType": "bitString"
}, - "priorityArray": {
- "title": "Priority Array",
- "readOnly": true,
- "prioritized": false,
- "type": "array",
- "metasysType": "array"
}, - "overrideExpirationTime": {
- "title": "Override Expiration Time",
- "readOnly": true,
- "prioritized": false,
- "type": "object",
- "metasysType": "struct"
}, - "currentCommandPriority": {
- "title": "Current Command Priority",
- "readOnly": true,
- "prioritized": false,
- "metasysType": "ushort",
- "type": "integer",
- "minimum": 0,
- "maximum": 65535
}, - "itemReference": {
- "title": "Item Reference",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "string"
}, - "name": {
- "title": "Name",
- "prioritized": false,
- "type": "string",
- "metasysType": "string"
}, - "objectName": {
- "title": "Object Name",
- "prioritized": false,
- "type": "string",
- "metasysType": "string"
}, - "description": {
- "title": "Description",
- "prioritized": false,
- "type": "string",
- "metasysType": "string"
}, - "status": {
- "title": "Status",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "enabled": {
- "title": "Enabled",
- "prioritized": false,
- "type": "boolean",
- "metasysType": "bool"
}, - "executionPriority": {
- "title": "Execution Priority",
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "objectCategory": {
- "title": "Authorization Category",
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "alarmState": {
- "title": "Alarm State",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "bacnetObjectType": {
- "title": "Object Type",
- "readOnly": true,
- "prioritized": false,
- "type": "string",
- "metasysType": "enum"
}, - "objectIdentifier": {
- "title": "Object Identifier",
- "readOnly": true,
- "prioritized": false,
- "metasysType": "bacOid",
- "oneOf": [
- {
- "$ref": "#bacoid"
}
]
}, - "propertyList": {
- "title": "Property List",
- "readOnly": true,
- "prioritized": false,
- "type": "array",
- "metasysType": "listof"
}
}, - "definitions": {
- "object-reference": {
- "$id": "#object-reference",
- "title": "Object reference data type",
- "type": "object",
- "oneOf": [
- {
- "properties": {
- "objectReference": {
- "format": "fully-qualified-reference",
- "type": "string"
}, - "referencedObject": {
- "type": "object",
- "properties": {
- "objectName": {
- "type": "string"
}, - "objectUrl": {
- "type": "string",
- "format": "uri"
}
}, - "readOnly": true
}
}, - "required": [
- "objectReference"
]
}, - {
- "properties": {
- "objectBACoid": {
- "readOnly": true,
- "oneOf": [
- {
- "$ref": "#bacoid"
}
]
}, - "deviceAddress": {
- "readOnly": true,
- "type": "string"
}, - "deviceBACoid": {
- "readOnly": true,
- "oneOf": [
- {
- "$ref": "#bacoid"
}
]
}
}, - "required": [
- "objectBACoid"
], - "additionalProperties": false
}
]
}, - "attribute-reference": {
- "$id": "#attribute-reference",
- "title": "Attribute reference data type",
- "type": "object",
- "allOf": [
- {
- "$ref": "#object-reference"
}, - {
- "properties": {
- "if": {
- "required": [
- "objectReference"
]
}, - "then": {
- "properties": {
- "referencedObject": {
- "properties": {
- "attributeUrl": {
- "type": "string",
- "metasysType": "string",
- "format": "uri"
}, - "attributeName": {
- "type": "string",
- "metasysType": "string"
}
}
}
}
}
}
}
]
}, - "bacoid": {
- "type": "object",
- "$id": "#bacoid",
- "title": "A definition for the BACoid data type",
- "properties": {
- "bacnetObjectType": {
- "title": "BACnet Object Type",
}, - "instance": {
- "type": "integer",
- "title": "Instance Number",
- "minimum": 0,
- "maximum": 4194303
}
}, - "required": [
- "bacnetObjectType",
- "instance"
], - "additionalProperties": false
}
}
}
}Returns an object payload containing the specified attribute. Invoke this
operation with a valid METASYS-SUBSCRIBE header to create a subscription
for changes to that attribute, rather than returning a value. The current
value and any updates to the attribute are instead sent over the specified
stream.
Licensing Restrictions
Requires Monitoring and Commanding API license.
See also:
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| attributeId required | string Examples:
metasysEnum: attributeEnumSet The attribute to read. The acceptable values for this parameter come from the See also:
|
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/attributes/presentValue \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
{- "item": {
- "presentValue": 72.5
}, - "condition": {
- "presentValue": {
- "priority": "writePriorityEnumSet.priorityDefault"
}
}, - "schema": {
- "type": "object",
- "language": "en-US",
- "title": "JCI AV",
- "version": "1.0",
- "properties": {
- "presentValue": {
- "title": "Present Value",
- "prioritized": true,
- "dynamic": true,
- "displayPrecisionSource": "displayPrecision",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}
}
}
}
}Returns a payload that lists all of the commands that an object supports.
Each command entry has an invokeUrl property, which is the URL needed to
invoke the command. In addition, each command entry has a
commandBodySchema property, which is a JSON schema that describes the
acceptable payload for the command. Commands are invoked using the HTTP
method PUT along with the invokeUrl and acceptable body.
Note: Some objects, such as multi-state values (MV) and binary values (BV),
may list a command that has a commandSet property and a property named
aggregateCommand with a value of true instead of invokeUrl. This
commandSet lists one or more commands. This entry is not a true command
but rather provides a hint to graphical user interfaces on how they may want
to group the commands of the commandSet under one command name. For
example, an MV object lists a command with the identifier
commandIdEnumSet.adjustCommand. This is not an actual command on an MV.
Instead the actual commands that could be used to present this command in a
UI are listed in the commandSet and they have identifiers like
commandIdEnumSet.multistate0Command. The Metasys User Interface displays
all of these commands as a single adjust command with the titles of the
individual commands as the parameter to send.
Licensing Restrictions
Requires Monitoring and Commanding API license.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/commands \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "items": [
- {
- "id": "commandIdEnumSet.adjustCommand",
- "title": "Adjust",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "priority": {
- "oneOf": [
- {
- "$ref": "#writePriorityEnumSet"
}, - {
- "type": "null"
}
]
}, - "parameters": {
- "type": "array",
- "metasysType": "list",
- "items": [
- {
- "id": "commandParmsEnumSet.valueCmdparm",
- "title": "Value",
- "displayPrecisionSource": "displayPrecision",
- "maxPresValueSource": "maxPresValue",
- "minPresValueSource": "minPresValue",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "minimum": -1.69999998e+38,
- "maximum": 1.69999998e+38,
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "default": 72.5
}
], - "minItems": 1,
- "maxItems": 1
}, - "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}, - "required": [ ],
- "additionalProperties": false
}, - "definitions": {
- "writePriorityEnumSet": {
- "title": "Write Priority",
- "$id": "#writePriorityEnumSet",
- "setId": 1
}
}
}
}, - {
- "id": "commandIdEnumSet.overrideCommand",
- "title": "Operator Override",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "parameters": {
- "type": "array",
- "metasysType": "list",
- "items": [
- {
- "id": "commandParmsEnumSet.valueCmdparm",
- "title": "Value",
- "displayPrecisionSource": "displayPrecision",
- "maxPresValueSource": "maxPresValue",
- "minPresValueSource": "minPresValue",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "minimum": -1.69999998e+38,
- "maximum": 1.69999998e+38,
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "default": 72.5
}
], - "minItems": 1,
- "maxItems": 1
}, - "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}, - "required": [ ],
- "additionalProperties": false
}, - "definitions": null
}
}, - {
- "id": "commandIdEnumSet.temporaryOverrideCommand",
- "title": "Temporary Override",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "parameters": {
- "type": "array",
- "metasysType": "list",
- "items": [
- {
- "id": "commandParmsEnumSet.valueCmdparm",
- "title": "Value",
- "displayPrecisionSource": "displayPrecision",
- "maxPresValueSource": "maxPresValue",
- "minPresValueSource": "minPresValue",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "minimum": -1.69999998e+38,
- "maximum": 1.69999998e+38,
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "default": 72.5
}, - {
- "id": "commandParmsEnumSet.hoursCmdparm",
- "title": "Hours",
- "metasysType": "ulong",
- "type": "integer",
- "minimum": 0,
- "maximum": 100,
- "default": 0
}, - {
- "id": "commandParmsEnumSet.minutesCmdparm",
- "title": "Minutes",
- "metasysType": "ulong",
- "type": "integer",
- "minimum": 0,
- "maximum": 59,
- "default": 0
}
], - "minItems": 3,
- "maxItems": 3
}, - "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}, - "required": [ ],
- "additionalProperties": false
}, - "definitions": null
}
}, - {
- "id": "commandIdEnumSet.overrideReleaseCommand",
- "title": "Release Operator Override",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}, - "required": [ ],
- "additionalProperties": false
}, - "definitions": null
}
}, - {
- "id": "commandIdEnumSet.releaseCommand",
- "title": "Release",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "parameters": {
- "type": "array",
- "metasysType": "list",
- "items": [
- {
- "id": "commandParmsEnumSet.attributeCmdparm",
- "title": "Attribute",
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#attributeEnumSet"
}
], - "default": "attributeEnumSet.presentValue"
}, - {
- "id": "commandParmsEnumSet.priorityCmdparm",
- "title": "Priority",
- "numberOfStates": 17,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#writePriorityEnumSet"
}
], - "default": "writePriorityEnumSet.priorityDefault"
}
], - "minItems": 2,
- "maxItems": 2
}, - "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}, - "required": [ ],
- "additionalProperties": false
}, - "definitions": {
- "attributeEnumSet": {
- "title": "Attribute",
- "$id": "#attributeEnumSet",
- "allOf": [
- {
- "oneOf": [
- {
- "const": "attributeEnumSet.presentValue",
- "title": "Present Value",
- "memberId": 85
}
]
},
], - "setId": 509
}, - "writePriorityEnumSet": {
- "title": "Write Priority",
- "$id": "#writePriorityEnumSet",
- "setId": 1
}
}
}
}, - {
- "id": "commandIdEnumSet.releaseAllCommand",
- "title": "Release All",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "parameters": {
- "type": "array",
- "metasysType": "list",
- "items": [
- {
- "id": "commandParmsEnumSet.attributeCmdparm",
- "title": "Attribute",
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#attributeEnumSet"
}
], - "default": "attributeEnumSet.presentValue"
}
], - "minItems": 1,
- "maxItems": 1
}, - "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}, - "required": [ ],
- "additionalProperties": false
}, - "definitions": {
- "attributeEnumSet": {
- "title": "Attribute",
- "$id": "#attributeEnumSet",
- "allOf": [
- {
- "oneOf": [
- {
- "const": "attributeEnumSet.presentValue",
- "title": "Present Value",
- "memberId": 85
}
]
},
], - "setId": 509
}
}
}
}, - {
- "id": "commandIdEnumSet.enableAlarmsCommand",
- "title": "Enable Alarms",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}, - "required": [ ],
- "additionalProperties": false
}, - "definitions": null
}
}, - {
- "id": "commandIdEnumSet.disableAlarmsCommand",
- "title": "Disable Alarms",
- "commandBodySchema": {
- "type": "object",
- "metasysType": "struct",
- "properties": {
- "annotation": {
- "title": "Annotation",
- "type": "string",
- "metasysType": "string",
- "minLength": 1,
- "maxLength": 255
}, - "required": [ ],
- "additionalProperties": false
}, - "definitions": null
}
}
], - "effectivePermissions": {
- "canInvoke": [
- "commandIdEnumSet.adjustCommand",
- "commandIdEnumSet.overrideCommand",
- "commandIdEnumSet.temporaryOverrideCommand",
- "commandIdEnumSet.overrideReleaseCommand",
- "commandIdEnumSet.releaseCommand",
- "commandIdEnumSet.releaseAllCommand",
- "commandIdEnumSet.enableAlarmsCommand",
- "commandIdEnumSet.disableAlarmsCommand"
]
}
}Used to invoke a command on an object. The payloads of commands differ, but
they share some similarities. To learn the specifics of the commands of an
object use List commands of an object (/objects/{objectId}/commands).
Licensing Restrictions
Requires Monitoring and Commanding API license.
See also:
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| commandId required | string Example: adjustCommand metasysEnum: commandIdEnumSet The identifier of the command to send. The acceptable values for this parameter come from the See also:
|
| priority | string (write-priority-enum-set) Enum: "writePriorityEnumSet.priorityNone" "writePriorityEnumSet.priorityManualEmergency" "writePriorityEnumSet.priorityFireApplications" "writePriorityEnumSet.priority3" "writePriorityEnumSet.priority4" "writePriorityEnumSet.priorityCriticalEquipment" "writePriorityEnumSet.priorityMinimumOnOff" "writePriorityEnumSet.priorityHeavyEquipDelay" "writePriorityEnumSet.priorityOperatorOverride" "writePriorityEnumSet.priority9" "writePriorityEnumSet.priority10" "writePriorityEnumSet.priorityDemandLimiting" "writePriorityEnumSet.priority12" "writePriorityEnumSet.priorityLoadRolling" "writePriorityEnumSet.priority14" "writePriorityEnumSet.prioritySchedulingOst" "writePriorityEnumSet.priorityDefault" metasysType: enum metasysEnum: writePriorityEnumSet |
| parameters | Array of any >= 0 items |
| annotation | string |
This body is used with the adjust command of an Analog Value (AV).
It sends the value 72.5 along with an annotation about why the
command was invoked. The URL for this command is
/objects/{objectId}/commands/adjustCommand
{- "parameters": [
- 72.5
], - "annotation": "Increase the set point to make it warmer."
}"Success"Many objects support nested objects. The obvious examples of this are
folder objects and device objects. Less obvious examples include objects
like analog value and multi-state value objects (which can have child
objects like integrations). This operation lists the types of objects that
can be created under an object.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/supportedChildTypes \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
The supported child types of a folder.
[- {
- "objectType": "mvClass",
- "description": "MV",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "mcClass",
- "description": "Multiple Command",
- "version": "2.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "intlClass",
- "description": "Interlock",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "calendarClass",
- "description": "Calendar",
- "version": "3.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "avClass",
- "description": "AV",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "bvClass",
- "description": "BV",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "optimalStartClass",
- "description": "Optimal Start",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "containerClass",
- "description": "Folder",
- "version": "1.0",
- "classification": "folder",
- "isAuthorized": true
}, - {
- "objectType": "globalDataClass",
- "description": "Global Data",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "signalSelectClass",
- "description": "Signal Select",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "pulseMeterClass",
- "description": "Pulse Meter",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "autoShutdownClass",
- "description": "Auto Shutdown",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "eeClass",
- "description": "Event Enrollment",
- "version": "2.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "bgrpClass",
- "description": "Group",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "flexAccumulatorClass",
- "description": "Accumulator",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "ieiejEdcClass",
- "description": "Electric Demand Control",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "ieiejGlcClass",
- "description": "Generator Load Control",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "solarClockClass",
- "description": "Solar Clock",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "scheduleClass",
- "description": "Schedule",
- "version": "3.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "loopClass",
- "description": "Loop",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "notificationClass",
- "description": "Notification",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "dataBroadcastClass",
- "description": "Data Broadcast",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "systemClass",
- "description": "Program",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}, - {
- "objectType": "trendLogNoextensionClass",
- "description": "Trend Log",
- "version": "1.0",
- "classification": "object",
- "isAuthorized": true
}
]Retrieves all equipment points mapped to attributes of this object.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "shortName" Enum: "category" "-category" "equipmentName" "-equipmentName" "isDisplayData" "-isDisplayData" "shortName" "-shortName" Example: sort=shortName The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/points?page=1&pageSize=100&sort=shortName' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "total": 1,
- "next": null,
- "previous": null,
- "items": [
- {
- "id": "b78fa672-3ec9-4794-bd00-7aeafeb9cde0",
- "itemReference": "{hostname}:{deviceHostname}/equipment.Controllers.VAV-1",
- "equipmentName": "VAV-1",
- "shortName": "ZN-T",
- "label": "Zone Temperature",
- "category": "",
- "isDisplayData": true,
- "attribute": "attributeEnumSet.presentValue"
}
],
}This operation is used to invoke multiple operations in a single HTTP request. Often a batch request is more efficient than sending each individual operation in its own HTTP request.
In this version of the API, the only objects related operation that can be used in a batch is Get attribute value.
If this operation is invoked with a valid METASYS-SUBSCRIBE header it will
cause a subscription to be created for the attributes in the request and rather
than returning any values, the current values and any updates to the attributes
will be sent over the specified stream.
Licensing Restrictions
Requires Monitoring and Commanding API license.
(INTERNAL) In addition to Get attribute value, internal clients may also use Change order of objects. All of the operations in a batch must be the same. You cannot mix Get attribute value with Change order of objects order.
(INTERNAL) Only the async version of Change order of objects is supported so a
METASYS-SUBSCRIBE header is required. If the header is not included the
overall operation will return a 400 with an appropriate error payload. The batch
version of Change order of objects will send one objects.ordering.update
event per request. The payload for the event will match the payload defined in
the Change order of objects operation.
(PRIVATE) Change order of objects implementation details
A batch request to change object ordering follows the schema for this operation.
{
"method": "PATCH",
"requests": [
{
"id": "1",
"relativeUrl": "3f8c1e32-4504-5d0a-9d8e-b695b059e272/objects/ordering",
"body": {
"items": [
"56d85c80-2741-5d4f-8f97-02877dd2c0e6",
"54c74311-4492-5f17-8caa-6ab69619402d"
]
}
}
]
}
Just like the single version of object ordering, each request should have synchronous error checking performed: duplicated child ids, invalid child ids, malformed request. (This could be done by delegating the call to the single versions or in some other way if that's more efficient.)
If the overall batch request is well formed and has at least one sub-request
that is valid, then the HTTP response should return a status of 200 . Each
sub-response that corresponds to a valid sub-request should have a status of
202 (Accepted) with a null body (The body property is required but null
is allowed as an option). The sub-requests that are not valid should return
sub-responses with error payloads following the schema already defined for this
batch operation:
parentId is not founderror is required.statusEnumSet,
if possible)Here's an example that shows a response to one valid request and one invalid request.
{
"requests": [
{
"id": "2",
"status": 202,
"body": null
}
{
"id": "3",
"status": 404,
"body": {
"error": {
"statusName": "dataIsOffBox",
"message": "No HTTP resource was found that matches the request URI.",
"details": "The parentId for this request was invalid."
}
}
}
]
}
The message string was chosen because it appears to be our standard error
message for all 404 errors. The details provide a user with more information
on what was wrong. The dataIsOffBox value was chosen for statusName because
it's display string is "Object does not exist"
If the overall batch request is malformed or has no valid sub-requests then the
HTTP response should return a 400 status code. The existing schema for a 400
response is simply a string. Provide as informative of a string as possible.
(Test with payloads of wrong type, without method, without requests, with
every item in requests having errors. )
See also:
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
| method required | string Value: "GET" The HTTP method to use for each request. This property is
restricted to (INTERNAL) The method |
required | Array of objects non-empty A collection of entries that represent the operations to invoke. |
This example shows a request body that will read the
presentValue and status from 3 different objects using
sequential numbers as request identifiers.
This example shows the use of sequential numeric values used as request identifiers but any unique strings can be used.
{- "method": "GET",
- "requests": [
- {
- "id": "1",
- "relativeUrl": "960534d2-7df5-5ed8-884c-164e7a2f280a/attributes/presentValue"
}, - {
- "id": "2",
- "relativeUrl": "960534d2-7df5-5ed8-884c-164e7a2f280a/attributes/status"
}, - {
- "id": "3",
- "relativeUrl": "c82d160b-884c-5eac-bad4-89754f0069e0/attributes/presentValue"
}, - {
- "id": "4",
- "relativeUrl": "c82d160b-884c-5eac-bad4-89754f0069e0/attributes/status"
}, - {
- "id": "5",
- "relativeUrl": "3abd9027-c572-5f6d-9de6-bfc044f899dc/attributes/presentValue"
}, - {
- "id": "6",
- "relativeUrl": "3abd9027-c572-5f6d-9de6-bfc044f899dc/attributes/status"
}
]
}This example shows the response to a read multiple attributes
request. Each operation response is uniquely identified by the
corresponding identifier (id) from the request.
{- "responses": [
- {
- "id": "1",
- "status": 200,
- "body": {
- "item": {
- "presentValue": 78.5
}, - "condition": {
- "presentValue": {
- "priority": "writePriorityEnumSet.priorityDefault"
}
}
}
}, - {
- "id": "2",
- "status": 200,
- "body": {
- "item": {
- "status": "objectStatusEnumSet.osNormal"
}, - "condition": { }
}
}, - {
- "id": "3",
- "status": 200,
- "body": {
- "item": {
- "presentValue": 50
}, - "condition": {
- "presentValue": {
- "priority": "writePriorityEnumSet.priorityDefault"
}
}
}
}, - {
- "id": "4",
- "status": 200,
- "body": {
- "item": {
- "status": "objectStatusEnumSet.osLowAlarm"
}, - "condition": { }
}
}, - {
- "id": "5",
- "status": 200,
- "body": {
- "item": {
- "presentValue": 78.5
}, - "condition": {
- "presentValue": {
- "priority": "writePriorityEnumSet.priorityDefault"
}
}
}
}, - {
- "id": "6",
- "status": 200,
- "body": {
- "item": {
- "status": "objectStatusEnumSet.osNormal"
}, - "condition": { }
}
}
]
}Delete a subscription to a resource in the objects domain.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
curl --request DELETE \ --url https:///%7Bhostname%7D/api/v5/objects/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Operations on time series sample data.
The Metasys system has two locations from which time series samples can be
retrieved. The first is from the trend or log object, itself. Each
object on the Metasys site whose responsibility is to generate samples
will have its own buffer to store them. When samples are retrieved from
the objects or networkDevice endpoints, they will be retrieved from
their respective buffers. Time series operations that work with a buffer
will include "(buffer)" in their summary.
The second location is from the repository. As samples are collected in
the trend or log objects themselves, those objects (if configured and
enabled) have the ability to forward that information to a repository.
The repository is the location on the LAN (Local Area Network) that can
receive and store historical data from one to many Metasys sources.
Samples retrieved from the timeSeries endpoint are retrieved from the
particular Metasys device's repository. Time series operations that work
with the repository will include "(repository)" in their summary.
Clients may subscribe to Objects and Network Devices streaming events. A
subscription is established by providing a METASYS-SUBSCRIBE header on a
GET operation of the samples resource under either the objects or
networkDevices resource paths.
The following events (with accompanying examples) are available for samples:
timeSeries.subscription.established - Indicates when a subscription
has been established for objects or networkDevices samples.
{
"subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"],
"message": "Sample subscription successful",
"total": 2,
"items": [
{
"id": "d7861b6a-d563-5521-a746-a68519cb7651",
"attribute": "presentValue",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"objectId": {
"type": "string"
},
"attribute": {
"allOf": [
{
"type": "string",
"metasysType": "enum"
},
{
"$ref": "https://{hostname}/api/v5/schemas/enums/attributesEnumSet"
}
]
},
"value": {
"type": "number",
"metasysType": "float",
"units": "unitEnumSet.degF",
"displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
},
"sampleTime": {
"type": "string",
"format": "date-time"
},
"reliability": {
"allOf": [
{
"type": "string",
"metasysType": "enum"
},
{
"$ref": "https://{hostname}/api/v5/schemas/enums/reliabilityEnumSet"
}
]
}
}
}
}
},
{
"id": "fe997524-a377-492b-bfb3-46a2f9807f42",
"attribute": "presentValue",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"objectId": {
"type": "string"
},
"attribute": {
"allOf": [
{
"type": "string",
"metasysType": "enum"
},
{
"$ref": "https://{hostname}/api/v5/schemas/enums/attributesEnumSet"
}
]
},
"value": {
"type": "boolean",
"metasysType": "bool"
},
"sampleTime": {
"type": "string",
"format": "date-time"
},
"reliability": {
"allOf": [
{
"type": "string",
"metasysType": "enum"
},
{
"$ref": "https://{hostname}/api/v5/schemas/enums/reliabilityEnumSet"
}
]
}
}
}
}
}
]
}
timeSeries.subscription.cancelled - Indicates when a subscription has
been cancelled for objects samples.
{
"subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
"message": "Sample subscription cancelled"
}
timeSeries.error - Indicates an error occurred with regards to an
active samples subscription.
{
"subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
"message": "The trend generating samples has been deleted."
}
timeSeries.samples.update - Indicates new samples have been generated.
Sample updates from multiple objects and attributes can be contained in
a single event (each designated by their id and attribute
properties).
{
"subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
"total": 2,
"items": [
{
"id": "d7861b6a-d563-5521-a746-a68519cb7651",
"attribute": "presentValue",
"value": 68.9,
"sampleTime": "2021-01-01T12:00:00Z",
"reliability": "reliabilityEnumSet.unreliable"
},
{
"id": "9e8a9f68-0a57-4ab0-83fd-38c15bbe787d",
"attribute": "presentValue",
"value": 67.9,
"sampleTime": "2021-01-01T12:01:00Z",
"reliability": "reliabilityEnumSet.unreliable"
}
]
}
timeSeries.heartbeat - Indicates that time series subscription(s) are
still alive.
{
"subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
"message": "ping from time series service @2021-08-04T16:03:23.3771485Z"
}
Retrieves a collection of attributes under the specified object for which samples are available in their respective local sample buffers.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Get objects trended attributes response.
{- "total": 2,
- "items": [
- {
- "attribute": "attributeEnumSet.memoryUsage"
}, - {
- "attribute": "attributeEnumSet.alarmRate"
}
],
}Retrieves a collection of samples from the object's local sample buffer for the specified object attribute during a particular date and time range.
If the METASYS-SUBSCRIBE header is provided, then an event subscription
will be created which will include the events described in
Time Series.
Note: The parent endpoint
/objects/{objectId}/trendedAttributes/{attributeId} is not currently
supported.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| attributeId required | string Example: presentValue metasysType: enum metasysEnum: attributeEnumSet The identifier of the attribute. The acceptable values for this parameter come from the See also:
|
| startSampleTime | string <date-time> Example: startSampleTime=2020-05-12T16:46:47Z The date and time representing the earliest sample to return. |
| endSampleTime | string <date-time> Example: endSampleTime=2021-01-19T18:13:58.007Z The date and time representing the latest sample to return. |
| sort | string Default: "-sampleTime" Enum: "sampleTime" "-sampleTime" Example: sort=sampleTime The criteria to use when sorting results. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes/presentValue/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&sort=sampleTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get samples from trend object response containing only analog values.
{- "total": 1,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "type": "number",
- "metasysType": "float",
- "units": "unitEnumSet.degF",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}, - "items": [
- {
- "value": 68.9,
- "sampleTime": "2021-01-01T12:00:00Z",
- "reliability": "reliabilityEnumSet.unreliable"
}
], - "attribute": "attributeEnumSet.presentValue",
}Retrieves a collection of attributes under the specified network device for which samples are available in their respective local sample buffer.
| id required | string Example: 6b092d2e-c795-4e90-95e8-5acafc74f19d The identifier of the network device. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/networkDevices/6b092d2e-c795-4e90-95e8-5acafc74f19d/trendedAttributes \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Get network devices trended attributes response.
{- "total": 2,
- "items": [
- {
- "attribute": "attributeEnumSet.memoryUsage"
}, - {
- "attribute": "attributeEnumSet.alarmRate"
}
],
}Retrieves a collection of samples from the network device's local sample buffer for the specified network device attribute during a particular date and time range.
If the METASYS-SUBSCRIBE header is provided, then an event subscription
will be created which will include the events described in
Time Series.
Note: The parent endpoint
/networkDevices/{id}/trendedAttributes/{attributeId} is not currently
supported.
| id required | string Example: c550095d-ee4c-4314-b415-b0577e383ee9 The identifier of the network device. |
| attributeId required | string Example: presentValue metasysType: enum metasysEnum: attributeEnumSet The identifier of the attribute. The acceptable values for this parameter come from the See also:
|
| startSampleTime | string <date-time> Example: startSampleTime=2020-05-12T16:46:47Z The date and time representing the earliest sample to return. |
| endSampleTime | string <date-time> Example: endSampleTime=2021-01-19T18:13:58.007Z The date and time representing the latest sample to return. |
| sort | string Default: "-sampleTime" Enum: "sampleTime" "-sampleTime" Example: sort=sampleTime The criteria to use when sorting results. |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/networkDevices/c550095d-ee4c-4314-b415-b0577e383ee9/trendedAttributes/presentValue/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&sort=sampleTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'
Get samples from trend object response containing only analog values.
{- "total": 1,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "type": "number",
- "metasysType": "float",
- "units": "unitEnumSet.degF",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}, - "items": [
- {
- "value": 68.9,
- "sampleTime": "2021-01-01T12:00:00Z",
- "reliability": "reliabilityEnumSet.unreliable"
}
], - "attribute": "attributeEnumSet.presentValue",
}This operation is used to invoke multiple time series operations in a single HTTP request. Often a batch request is more efficient than sending each individual operation in its own HTTP request. In this version of the API, the only time series related operations that can be used in this batch API are List object trended attributes (buffer) and Get object samples (buffer). This request is for fetching buffer data (as opposed to fetching data from the repository).
| method required | string Value: "GET" The HTTP method to use for each request. This property is
restricted to |
required | Array of objects (Request object) non-empty A collection of entries that represent the operations to invoke. |
This example shows a request body that will read samples for the
presentValue and enabled attributes for object
960534d2-7df5-5ed8-884c-164e7a2f280a and for the
presentValue attribute of object
c82d160b-884c-5eac-bad4-89754f0069e0.
{- "method": "GET",
- "requests": [
- {
- "id": "1",
- "relativeUrl": "960534d2-7df5-5ed8-884c-164e7a2f280a/trendedAttributes/presentValue/samples"
}, - {
- "id": "2",
- "relativeUrl": "960534d2-7df5-5ed8-884c-164e7a2f280a/trendedAttributes/enabled/samples?startSampleTime=2021-05-23T04:39:01.545Z&endSampleTime=2021-05-24T04:39:01.545Z&sort=-sampleTime&extensionId={trendExtensionId}"
}, - {
- "id": "3",
- "relativeUrl": "c82d160b-884c-5eac-bad4-89754f0069e0/trendedAttributes/presentValue/samples"
}
]
}Post Batch Buffer sample response
{- "responses": [
- {
- "id": "1",
- "status": 200,
- "body": {
- "total": 1,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "type": "number",
- "metasysType": "float",
- "units": "unitEnumSet.degF",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}, - "items": [
- {
- "value": 68.9,
- "sampleTime": "2021-01-01T12:00:00Z",
- "reliability": "reliabilityEnumSet.unreliable"
}
], - "attribute": "attributeEnumSet.presentValue"
}
}, - {
- "id": "2",
- "status": 200,
- "body": {
- "total": 1,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "type": "boolean",
- "metasysType": "bool"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}, - "items": [
- {
- "value": true,
- "sampleTime": "2021-01-01T12:00:00Z",
- "reliability": "reliabilityEnumSet.unreliable"
}
], - "attribute": "attributeEnumSet.outOfService"
}
}, - {
- "id": "3",
- "status": 404,
- "body": {
- "code": "invalidObjectId",
- "message": "Invalid Object ID"
}
}
]
}The operation retrieves a collection of resources for which historical time series data exists. This operation uses the time series repository as its source of truth. It may contain data for objects that no longer actually exist on the site. This operation never considers time series that exist exclusively in buffers on devices and that are not configured to forward their samples to the repository.
| searchString | string Examples:
Filter results by finding objects with an |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 2000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "itemReference" Enum: "itemReference" "-itemReference" Example: sort=itemReference The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/timeSeries?searchString=AV&page=1&pageSize=100&sort=itemReference' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "total": 2,
- "next": null,
- "previous": null,
- "items": [
- {
- "id": "c82d160b-884c-5eac-bad4-89754f0069e0",
- "itemReference": "{hostname}:{deviceHostname}/AV2",
- "name": "AV2",
- "sampledAttributes": [
- {
- "attribute": "attributeEnumSet.presentValue"
}
]
}, - {
- "id": "0e59b020-4b6d-5498-8c56-82d95709c5a7",
- "itemReference": "{hostname}:{deviceHostname}/Programming.AV3",
- "name": "AV3",
- "sampledAttributes": [
- {
- "attribute": "attributeEnumSet.presentValue"
}
]
}
],
}Retrieves a collection of attributes for the specified object for which samples are available in the trend repository.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/timeSeries/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Get trended attributes from the trend repository response.
{- "total": 2,
- "items": [
- {
- "attribute": "attributeEnumSet.memoryUsage"
}, - {
- "attribute": "attributeEnumSet.alarmRate"
}
],
}Retrieves a collection of samples from the trend repository for the
specified object attribute during a particular date and time range. Note:
The parent endpoint
/timeSeries/{objectId}/trendedAttributes/{attributeId} is not currently
supported.
| objectId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The identifier of the object. |
| attributeId required | string Example: presentValue metasysType: enum metasysEnum: attributeEnumSet The identifier of the attribute. The acceptable values for this parameter come from the See also:
|
| startSampleTime | string <date-time> Example: startSampleTime=2020-05-12T16:46:47Z The date and time representing the earliest sample to return. |
| endSampleTime | string <date-time> Example: endSampleTime=2021-01-19T18:13:58.007Z The date and time representing the latest sample to return. |
| page | integer >= 1 Default: 1 Example: page=5 The page of the collection being requested. |
| pageSize | integer <= 20000 Default: 500 Example: pageSize=500 The requested number of items in the response. |
| sort | string Default: "-sampleTime" Enum: "sampleTime" "-sampleTime" Example: sort=sampleTime The criteria to use when sorting results. Please refer to default sorting rules for general guidelines. |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/timeSeries/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes/presentValue/samples?startSampleTime=2020-05-12T16%3A46%3A47Z&endSampleTime=2021-01-19T18%3A13%3A58.007Z&page=5&pageSize=500&sort=sampleTime' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Get samples from the trend repository response containing only analog values.
{- "total": 1,
- "schema": {
- "type": "array",
- "items": {
- "type": "object",
- "properties": {
- "value": {
- "type": "number",
- "metasysType": "float",
- "units": "unitEnumSet.degF",
- "displayPrecision": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "sampleTime": {
- "type": "string",
- "format": "date-time"
}, - "reliability": {
- "allOf": [
- {
- "type": "string",
- "metasysType": "enum"
},
]
}
}
}
}, - "items": [
- {
- "value": 68.9,
- "sampleTime": "2021-01-01T12:00:00Z",
- "reliability": "reliabilityEnumSet.unreliable"
}
], - "attribute": "attributeEnumSet.presentValue",
}Creates a subscription to trend buffer samples
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| METASYS-SUBSCRIBE | string Example: 40e47e37-0f24-4101-8e1d-de96af4b648b If present, subscribes the client for streaming events associated with the
resource. The value of this header is a stream id obtained by opening a
stream with Get a stream. The response will have a
See also: |
New streaming subscription for time series data.
Array of objects Collection of items to sign up for. |
{- "items": [
- {
- "objectId": "c550095d-ee4c-4314-b415-b0577e383ee9",
- "attributeId": "presentValue"
}
]
}Replaces an existing subscription to trend buffer samples.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
Streaming subscription for time series data.
Array of objects Collection of items to sign up for. |
{- "items": [
- {
- "objectId": "c550095d-ee4c-4314-b415-b0577e383ee9",
- "attributeId": "presentValue"
}
]
}Deletes a subscription to trend samples.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
curl --request DELETE \ --url https:///%7Bhostname%7D/api/v5/timeSeries/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This operation retrieves the specified enumeration as a JSON schema. The path of this operation appears in several schemas of object payloads.
To get a list of all enumerations fetch the enumerationSetNamesEnumSet:
GET /schemas/enums/enumerationSetNamesEnumSet
See also:
| enumId required | string Examples:
metasysType: enum The enumeration to retrieve. The acceptable values for this parameter come from the
|
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/schemas/enums/writePriorityEnumSet \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
{- "title": "Write Priority",
- "setId": 1,
- "oneOf": [
- {
- "const": "writePriorityEnumSet.priorityNone",
- "title": "0 (No Priority)",
- "memberId": 0
}, - {
- "const": "writePriorityEnumSet.priorityManualEmergency",
- "title": "1 (Manual Life Safety)",
- "memberId": 1
}, - {
- "const": "writePriorityEnumSet.priorityFireApplications",
- "title": "2 (Auto Life Safety)",
- "memberId": 2
}, - {
- "const": "writePriorityEnumSet.priority3",
- "title": "3 (Application)",
- "memberId": 3
}, - {
- "const": "writePriorityEnumSet.priority4",
- "title": "4 (Application)",
- "memberId": 4
}, - {
- "const": "writePriorityEnumSet.priorityCriticalEquipment",
- "title": "5 (Critical Equipment)",
- "memberId": 5
}, - {
- "const": "writePriorityEnumSet.priorityMinimumOnOff",
- "title": "6 (Minimum On Off)",
- "memberId": 6
}, - {
- "const": "writePriorityEnumSet.priorityHeavyEquipDelay",
- "title": "7 (Heavy Equip Delay)",
- "memberId": 7
}, - {
- "const": "writePriorityEnumSet.priorityOperatorOverride",
- "title": "8 (Operator Override)",
- "memberId": 8
}, - {
- "const": "writePriorityEnumSet.priority9",
- "title": "9 (Application)",
- "memberId": 9
}, - {
- "const": "writePriorityEnumSet.priority10",
- "title": "10 (Application)",
- "memberId": 10
}, - {
- "const": "writePriorityEnumSet.priorityDemandLimiting",
- "title": "11 (Demand Limiting)",
- "memberId": 11
}, - {
- "const": "writePriorityEnumSet.priority12",
- "title": "12 (Application)",
- "memberId": 12
}, - {
- "const": "writePriorityEnumSet.priorityLoadRolling",
- "title": "13 (Load Rolling)",
- "memberId": 13
}, - {
- "const": "writePriorityEnumSet.priority14",
- "title": "14 (Application)",
- "memberId": 14
}, - {
- "const": "writePriorityEnumSet.prioritySchedulingOst",
- "title": "15 (Scheduling)",
- "memberId": 15
}, - {
- "const": "writePriorityEnumSet.priorityDefault",
- "title": "16 (Default)",
- "memberId": 16
}
]
}This endpoint retrieves a schema for a specific objectType. The schema
describes the properties that can be set when creating an object of the
specific type.
| objectType required | string Examples:
metasysEnum: objectTypeEnumSet The type of object The acceptable values for this parameter come from the See also:
|
| parentId required | string Example: parentId=2993aed9-5765-5641-889c-40ec968c8a82 The object under which this new object will be created. |
| extendedProperty | string Examples:
metasysEnum: attributeEnumSet The attribute to extend. Indicates which attribute of the parent object the extension should be linked to. Used only for extension objects (like alarm extensions). The acceptable values for this parameter come from the See also:
|
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/schemas/objectTypes/objectTypeEnumSet.avClass?parentId=2993aed9-5765-5641-889c-40ec968c8a82&extendedProperty=attributeEnumSet.presentValue' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This schema describes the properties that can be configured when creating an object of the type avClass.
{- "schema": {
- "$comment": "Some parts of this schema have been truncated for space reasons. Where this has been done it has been noted.",
- "type": "object",
- "title": "JCI AV",
- "language": "en-us",
- "version": "1.0",
- "properties": {
- "name": {
- "title": "Name",
- "category": "attributeCategoryEnumSet.nameCategory",
- "type": "string",
- "metasysType": "string",
- "maxLength": 400,
- "default": ""
}, - "description": {
- "title": "Description",
- "oneOf": [
- {
- "type": "string"
}, - {
- "type": "null"
}
], - "metasysType": "string",
- "maxLength": 64
}, - "bacnetObjectType": {
- "title": "Object Type",
- "readOnly": true,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#objectTypeEnumSet"
}
], - "default": "objectTypeEnumSet.bacAvClass"
}, - "objectCategory": {
- "title": "Authorization Category",
- "category": "attributeCategoryEnumSet.objectCategoryCategory",
- "numberOfStates": 250,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#objectCategoryEnumSet"
}
], - "default": "objectCategoryEnumSet.generalCategory"
}, - "prioritySupported": {
- "title": "Priority Supported",
- "type": "boolean",
- "metasysType": "bool",
- "default": true
}, - "minPresValue": {
- "title": "Min Value",
- "displayPrecisionSource": "displayPrecision",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "default": -1.69999997607218e+38
}, - "maxPresValue": {
- "title": "Max Value",
- "displayPrecisionSource": "displayPrecision",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "default": 1.69999997607218e+38
}, - "units": {
- "title": "Units",
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#unitEnumSet"
}
], - "default": "unitEnumSet.noUnits"
}, - "displayPrecision": {
- "title": "Display Precision",
- "numberOfStates": 13,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#displayPrecisionEnumSet_endAt_13"
}
], - "default": "displayPrecisionEnumSet.displayPrecisionPt1"
}, - "covIncrement": {
- "title": "COV Increment",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "minimum": 0,
- "default": 0.01
}, - "relinquishDefault": {
- "title": "Relinquish Default",
- "displayPrecisionSource": "displayPrecision",
- "maxPresValueSource": "maxPresValue",
- "minPresValueSource": "minPresValue",
- "unitsSource": "units",
- "metasysType": "float",
- "type": "number",
- "minimum": -1.69999997607218e+38,
- "maximum": 1.69999997607218e+38,
- "displayPrecision": {
- "id": "displayPrecisionEnumSet.displayPrecisionPt1",
- "displayMultipleOf": 0.1
}, - "default": 0
}, - "restoreCommandPriority": {
- "title": "Restore Command Priority",
- "category": "attributeCategoryEnumSet.restoreCommandPriorityCategory",
- "type": "array",
- "metasysType": "flags",
- "maxItems": 4,
- "minItems": 4,
- "items": {
- "type": "array",
- "items": [
- {
- "$ref": "#restorePriorityEnumSet"
}, - {
- "type": "boolean"
}
]
}, - "uniqueItems": true,
- "default": [
- [
- "restorePriorityEnumSet.7",
- true
], - [
- "restorePriorityEnumSet.10",
- false
], - [
- "restorePriorityEnumSet.12",
- false
], - [
- "restorePriorityEnumSet.15",
- false
]
]
}, - "connectedTo": {
- "title": "Connected To",
- "oneOf": [
- {
- "type": "null"
}, - {
- "$ref": "#attribute-reference"
}
], - "metasysType": "attributeReference",
- "attributeFilter": "basic"
}, - "direction": {
- "title": "Direction",
- "numberOfStates": 3,
- "type": "string",
- "metasysType": "enum",
- "oneOf": [
- {
- "$ref": "#connectionDirectionSet_endAt_3"
}
], - "default": "connectionDirectionSet.notConnected"
}, - "priorityForWritingToConnected": {
- "title": "Priority For Writing to Connected Object",
- "metasysType": "byte",
- "type": "integer",
- "minimum": 1,
- "maximum": 16,
- "default": 16
}
}, - "definitions": {
- "objectTypeEnumSet": {
- "title": "Object Type",
- "$id": "#objectTypeEnumSet",
- "allOf": [
- {
- "oneOf": [
- {
- "const": "objectTypeEnumSet.bacAvClass",
- "title": "AV",
- "memberId": 2
}
]
},
], - "setId": 508
}, - "objectCategoryEnumSet": {
- "title": "Authorization Category",
- "$id": "#objectCategoryEnumSet",
- "allOf": [
- {
- "$comment": "The following list was truncated down to one entry for space reasons. Normally it would contain more entries.",
- "oneOf": [
- {
- "const": "objectCategoryEnumSet.hvacCategory",
- "title": "HVAC",
- "memberId": 0
}
]
},
], - "setId": 33
}, - "unitEnumSet": {
- "title": "Unit",
- "$id": "#unitEnumSet",
- "allOf": [
- {
- "$comment": "The following list was truncated down to one entry for space reasons. Normally it would contain more entries.",
- "oneOf": [
- {
- "const": "unitEnumSet.squareMeters",
- "title": "sq meter",
- "memberId": 0
}
]
},
], - "setId": 507
}, - "displayPrecisionEnumSet_endAt_13": {
- "title": "Display Precision",
- "$id": "#displayPrecisionEnumSet_endAt_13",
- "allOf": [
- {
- "$comment": "The following list was truncated down to one entry for space reasons. Normally it would contain more entries.",
- "oneOf": [
- {
- "const": "displayPrecisionEnumSet.displayPrecisionPt000001",
- "title": "1000000ths",
- "memberId": 0
}
]
},
], - "setId": 0
}, - "restorePriorityEnumSet": {
- "title": "Restore Priority",
- "$id": "#restorePriorityEnumSet",
- "allOf": [
- {
- "$comment": "The following list was truncated down to one entry for space reasons. Normally it would contain more entries.",
- "oneOf": [
- {
- "const": "restorePriorityEnumSet.7",
- "title": "Operator Override",
- "memberId": 7
}
]
},
], - "setId": 357
}, - "object-reference": {
- "$id": "#object-reference",
- "title": "Object reference data type",
- "type": "object",
- "properties": {
- "objectReference": {
- "format": "fully-qualified-reference",
- "type": "string"
}, - "referencedObject": {
- "type": "object",
- "properties": {
- "objectName": {
- "type": "string"
}, - "objectUrl": {
- "type": "string",
- "format": "uri"
}
}, - "readOnly": true
}
}
}, - "attribute-reference": {
- "$id": "#attribute-reference",
- "title": "Attribute reference data type",
- "allOf": [
- {
- "type": "object",
- "properties": {
- "attributeTitle": {
- "type": "string"
}, - "referencedObject": {
- "properties": {
- "attributeUrl": {
- "type": "string",
- "format": "uri"
}
}
}
}
}, - {
- "$ref": "#object-reference"
}
]
}, - "connectionDirectionSet_endAt_3": {
- "title": "Connection Value Direction",
- "$id": "#connectionDirectionSet_endAt_3",
- "allOf": [
- {
- "$comment": "The following list was truncated down to one entry for space reasons. Normally it would contain more entries.",
- "oneOf": [
- {
- "const": "connectionDirectionSet.sendsValueTo",
- "title": "Sends Value To",
- "memberId": 0
}
]
},
], - "setId": 3102
}
}, - "required": [
- "name",
- "objectCategory",
- "prioritySupported",
- "minPresValue",
- "maxPresValue",
- "units",
- "displayPrecision",
- "covIncrement",
- "relinquishDefault",
- "restoreCommandPriority",
- "direction",
- "priorityForWritingToConnected"
]
}, - "views": [
- {
- "title": "Configuration",
- "views": [
- {
- "title": "Basic",
- "views": [
- {
- "title": "Object",
- "properties": [
- "name",
- "description",
- "bacnetObjectType",
- "objectCategory"
], - "id": "viewGroupEnumSet.objectGrp"
}, - {
- "title": "Engineering Values",
- "properties": [
- "prioritySupported",
- "minPresValue",
- "maxPresValue"
], - "id": "viewGroupEnumSet.engValuesGrp"
}, - {
- "title": "Display",
- "properties": [
- "units",
- "displayPrecision",
- "covIncrement"
], - "id": "viewGroupEnumSet.displayGrp"
}, - {
- "title": "Default State",
- "properties": [
- "relinquishDefault"
], - "id": "viewGroupEnumSet.defaultStateGrp"
}, - {
- "title": "Restart Options",
- "properties": [
- "restoreCommandPriority"
], - "id": "viewGroupEnumSet.restartOptionsGrp"
}, - {
- "title": "Connection Status",
- "properties": [
- "connectedTo",
- "direction",
- "priorityForWritingToConnected"
], - "id": "viewGroupEnumSet.connectionStatusGrp"
}
], - "id": "groupTypeEnumSet.basicGrpType"
}, - {
- "title": "Advanced",
- "views": [ ],
- "id": "groupTypeEnumSet.advancedGrpType"
}
], - "id": "viewNameEnumSet.configView"
}
]
}This operation is used to suggest values for identification properties for
the next object created in a specific location of a specific type. The
properties in question are name and localUniqueIdentifier. (The
localUniqueIdentifier isn't a true object property but it is a query
parameter used when creating an object and the value is used to generate the
itemReference property of an object.)
Note: there is no guarantee that the suggested values are still available at the time a client decides to use them to create a new object.
Note: For field controller objects, additional properties may also be
returned in addition to name and localUniqueIdentifier.
| objectType required | string Examples:
metasysEnum: objectTypeEnumSet The type of object The acceptable values for this parameter come from the See also:
|
| parentObjectId required | string Example: parentObjectId=b3ca663c-36c1-584f-9462-83d7b3d0349d An object ID that specifies the location in which a new object is intended to be created. The response payload will then contain identification values that are valid for that location. |
| extendedProperty | string Examples:
metasysEnum: attributeEnumSet The attribute to extend. Indicates which attribute of the parent object the extension should be linked to. Used only for extension objects (like alarm extensions). The acceptable values for this parameter come from the See also:
|
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/schemas/objectTypes/objectTypeEnumSet.avClass/identification?parentObjectId=b3ca663c-36c1-584f-9462-83d7b3d0349d&extendedProperty=attributeEnumSet.presentValue' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
This payload includes a schema that describes the name and localUniqueIdentifier properties and includes a default value for each. This default value for localUniqueIdentifier will always be unique for the given location at the time it is requested.
{- "schema": {
- "type": "object",
- "properties": {
- "name": {
- "type": "string",
- "metasysType": "string",
- "default": "AV1",
- "maxLength": 400
}, - "localUniqueIdentifier": {
- "type": "string",
- "metasysType": "string",
- "default": "AV1",
- "maxLength": 32
}
}
}
}NOTE: The scope of this group of operations is under development and may change at any time.
This section describes the operations you can perform in the context of a site. A site represents a BAS installation at a given location, which may be a single building or multiple buildings. Use site operations to get a semantic model of the entire site.
Gets the explicit semantic knowledge facts of the site. A fact is an explicit statement, or RDF triple, that has been defined for the site.
In contrast, an inferred fact is a derived statement or piece of knowledge based on explicit facts and ontologies from which the explicit facts are associated to. Inferred facts of the site will not be included in the response of this operation. You will need to obtain the referenced ontologies from their available locations and apply your own set of inference rules in ways that are appropriate for your usage.
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/site/rdf \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . @prefix data: <http://data.jci.com/data#> . @prefix jcb: <http://ontologies.jci.com/bacnetObjectModel#> . @prefix jc: <http://ontologies.jci.com/core#> . data:975b6588-2bca-5823-b3d6-4c0261b338e3 a jc:Supervisory_Controller; jcb:itemReference "{hostname}:{deviceHostname}"; rdfs:label "My Engine"; jcb:objectType 8; jcb:objectInstance 1 .
Retrieves the collection of spaces served by the specified network device. A space is served by a network device when any equipment instance serving the space defines points that map to an attribute of any object contained on the network device.
| networkDeviceId required | string Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7 The identifier of a network device. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/spaces?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of spaces.
{- "total": 1,
- "items": [
- {
- "id": "bf254f63-2cbb-4195-8c53-a1d6fcbe54f6",
- "itemReference": "{hostname}:{deviceHostname}/Campus",
- "name": "Campus",
- "type": "spaceTypesEnumSet.generic",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices"
}
], - "next": null,
- "previous": null,
}Retrieves the collection of spaces served by the specified equipment instance.
| equipmentId required | string Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0 The identifier of the equipment instance. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/spaces?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of spaces.
{- "total": 1,
- "items": [
- {
- "id": "bf254f63-2cbb-4195-8c53-a1d6fcbe54f6",
- "itemReference": "{hostname}:{deviceHostname}/Campus",
- "name": "Campus",
- "type": "spaceTypesEnumSet.generic",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices"
}
], - "next": null,
- "previous": null,
}Retrieves a collection of spaces.
| type | string Example: type=spaceTypesEnumSet.building metasysType: enum metasysEnum: spaceTypesEnumSet Type of space to return. The acceptable values for this parameter come from the See also:
|
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/spaces?type=spaceTypesEnumSet.building&page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of spaces.
{- "total": 1,
- "items": [
- {
- "id": "bf254f63-2cbb-4195-8c53-a1d6fcbe54f6",
- "itemReference": "{hostname}:{deviceHostname}/Campus",
- "name": "Campus",
- "type": "spaceTypesEnumSet.generic",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices"
}
], - "next": null,
- "previous": null,
}Retrieves the specified space.
| spaceId required | string Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 The identifier of a space. |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of spaces.
{- "id": "bf254f63-2cbb-4195-8c53-a1d6fcbe54f6",
- "itemReference": "{hostname}:{deviceHostname}/Campus",
- "name": "Campus",
- "type": "spaceTypesEnumSet.generic",
- "parentUrl": null,
- "networkDevicesUrl": "https://{hostname}/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices"
}Retrieves the collection of spaces that are located within the specified space.
| spaceId required | string Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 The identifier of a space. |
| page | integer >= 1 Default: 1 Example: page=1 The page number of items to return. |
| pageSize | integer [ 1 .. 1000 ] Default: 100 Example: pageSize=100 The maximum number of items to return in the response. |
| sort | string Default: "name" Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId" Example: sort=name The criteria to use when sorting results (see rules). |
curl --request GET \ --url 'https:///%7Bhostname%7D/api/v5/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/spaces?page=1&pageSize=100&sort=name' \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
A page of spaces.
{- "total": 1,
- "items": [
- {
- "id": "ca8fbdbb-8e44-41fd-a765-da18de80a8f1",
- "itemReference": "{hostname}:{deviceHostname}/Campus.Building",
- "name": "Building",
- "type": "spaceTypesEnumSet.building",
- "networkDevicesUrl": "https://{hostname}/api/v5/spaces/ca8fbdbb-8e44-41fd-a765-da18de80a8f1/networkDevices"
}
], - "next": null,
- "previous": null,
}Operations for managing subscriptions to status information for network devices and trees.
Clients may subscribe to several different types of status information, including:
device summary is a high level overview of the entire site. It
provides a list of all non ok statuses occurring on each network
device, grouped by network device.
device details provides a list of all objects with non ok status for
a single network device of interest.
tree details provides a list of all objects with non ok status for a
single tree of interest.
The device summary is used by the Metasys User Interface (MUI) to overlay status indicators (icons) on the unexpanded Building Network tree. When a user expands a network device, MUI subscribes for device details for that device. The device details allow MUI to overlay status indicators on the child objects of that network device. When a user expands a different network device, three things happen:
This is an example of a well behaved client, because device details are not subscribed before they are needed and device details are unsubscribed when they are no longer needed.
Tree details is very similar to device details, except that the scope of the subscription is for a tree (formerly called "User Views" in the Site Management Portal).
Both device details and tree details employ the concepts of rank and
propagates. Rank is the severity of the status, with a higher rank
being more severe. When multiple statuses apply, Metasys user interfaces
show the one with the highest rank. Propagates is a hint as to how to
apply a status to the hierarchy. For example, if a field controller
connected to a network device goes offline
(objectStatusEnumSet.osOffline), then that status would be accompanied
with a hint to propagate down to all children of that field device
(propagates: down). These hints help the event message be succinct and
not have to include an entry for each child object. Propagation is up
for objectStatusEnumSet.osLowAlarm, to indicate there is some object in
an alarm state on this network device. And finally, sometimes there is no
propagation. Such is the case for objectStatusEnumSet.osInactive.
The following events (with accompanying examples) are available for status indicators:
statusIndicators.subscription.cancelled - Indicates when a
subscription has been cancelled by the system. The subscription has
removed and no more updates will arrive for this subscription. Try to
subscribe again, but if the problem persists, please contact to your
system administrator.
{
"subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"]
}
statusIndicators.networkDeviceSummary.update - Indicates a change in
device summary status.
{
"subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"],
"items": [
// an "item" for each network device on the site
// note: due to Streaming event size limits, entire update may be split across multiple events
{
"id": "guid of device",
// Most severe non-OK status amongst all objects on the network device
// (excluding any offline field devices) or defaults to objectStatusEnumSet.osNormal.
"summarizedStatus": "objectStatusEnumSet.osLowAlarm",
// List of all non-OK statuses for objects on the network device
"objectStatuses": [
"objectStatusEnumSet.osOffline",
"objectStatusEnumSet.osLowAlarm",
"objectStatusEnumSet.osHighWarning",
"objectStatusEnumSet.osInactive"
]
}
]
}
statusIndicators.networkDeviceDetails.update - Indicates a change in
network device detail status.
{
"subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"],
"items": [
// an "item" for each supervisory device on the site
// note: due to Streaming event size limits, entire update may be split across multiple events
{
"id": "guid of device",
"objects": [
{
// one "object" for each non-OK object on the supervisory device
"id": "guid of object 1",
"objectStatus": "objectStatusEnumSet.osInactive",
"propagates": "none",
"rank": 1
},
{
"id": "guid of object 2",
"objectStatus": "objectStatusEnumSet.osLowAlarm",
"propagates": "up", // up: ancestor nodes
"rank": 30
},
{
"id": "guid of object 3",
"objectStatus": "objectStatusEnumSet.osOffline",
"propagates": "down", // down: child nodes
"rank": 112
}
]
}
]
}
statusIndicators.treeDetails.update - Indicates a change in tree
detail status.
{
"subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"],
"total": 2,
"items": [
// an "item" for each tree
// note: due to Streaming event size limits, entire update may be split across multiple events
{
"id": "guid of tree (user view)",
"objects": [
{
// one "object" for each non-OK object in the tree
"id": "guid of object 1",
"objectStatus": "objectStatusEnumSet.osInactive",
"propagates": "none",
"rank": 1
},
{
"id": "guid of object 2",
"objectStatus": "objectStatusEnumSet.osLowAlarm",
"propagates": "up", // up: ancestor nodes
"rank": 30
},
{
"id": "guid of object 3",
"objectStatus": "objectStatusEnumSet.osOffline",
"propagates": "none", // field controller offline doesn't propagate in user views
"rank": 112
}
]
}
]
}
statusIndicators.heartbeat - Affirms subscription(s) that are still
active.
{
"subscriptionIds": ["07606e13-e0f2-4f2c-898a-3745bdfcf9a7"],
"message": "ping from status indicator service @2021-08-04T16:03:23.3771485Z"
}
Create a subscription to network device summary, detailed status of network device(s) and detailed status of tree(s).
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
Used to convey the desired subscription.
| networkDeviceSummary | boolean Indicate if network device summary information is desired. |
| networkDeviceDetails | Array of strings Array of network device identifiers to subscribe for status details. |
| treeDetails | Array of strings Array of tree identifiers to subscribe for status details. |
{- "networkDeviceSummary": true,
- "networkDeviceDetails": [
- "e62509b0-bf40-49bd-a457-9775bc48e2af",
- "f62509b0-bf40-49bd-a457-9775bc48e2af"
], - "treeDetails": [
- "264ddedf-498c-49e6-bfb9-bc05544f7819"
]
}The request body contains unrecognized network device id(s).
{- "code": "api:error.deviceNotFound",
- "message": "Could not find network device(s) by ID.",
- "details": {
- "deviceId": "d9bf66bd-22f8-425b-82a4-44ba153d79c7"
}
}Modify a subscription to network device summary, detailed status of network device(s) and detailed status of tree(s).
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
Used to convey the desired subscription.
| networkDeviceSummary | boolean Indicate if network device summary information is desired. |
| networkDeviceDetails | Array of strings Array of network device identifiers to subscribe for status details. |
| treeDetails | Array of strings Array of tree identifiers to subscribe for status details. |
{- "networkDeviceSummary": true,
- "networkDeviceDetails": [
- "e62509b0-bf40-49bd-a457-9775bc48e2af",
- "f62509b0-bf40-49bd-a457-9775bc48e2af"
], - "treeDetails": [
- "264ddedf-498c-49e6-bfb9-bc05544f7819"
]
}The request body contains unrecognized network device id(s).
{- "code": "api:error.deviceNotFound",
- "message": "Could not find network device(s) by ID.",
- "details": {
- "deviceId": "d9bf66bd-22f8-425b-82a4-44ba153d79c7"
}
}Deletes a subscription to status indicators.
| streamId required | string Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb The stream identifier that contains the subscription. This is the unique
identifier for the client's stream obtained via |
| subscriptionId required | string Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5 The identifier of the subscription to act upon. This is the unique
identifier to the subscription for a specific resource or type of event.
This value is found as the last parameter of a
|
curl --request DELETE \ --url https:///%7Bhostname%7D/api/v5/statusIndicators/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'
Your Metasys system works continuously: sensors report current conditions, algorithms make adjustments, and alarms alert operators to potential issues. Streaming is how the Metasys API provides access to these events using the HTML standard server-sent events (SSE). For further information, refer to Mozilla developer guide. In this document, Streaming typically refers to the Metasys feature and stream refers to the concept of the HTTP connection and the flow of data.
Per the standard, a server-sent event usually contains three components, separated by newline, with the last component having a second newline to mark the end of the event.
id: <event id>\n
event: <event type>\n
data: <event data>\n\n
| Line Prefix | Explanation |
|---|---|
id |
ordering id to enable the "pick up where you left off" reconnection |
event |
message type |
data |
message payload as a JSON string |
Example:
id: b6d184ee-e137-44aa-b9b1-14bc704cd25d:1\n
event: hello\n
data: b6d184ee-e137-44aa-b9b1-14bc704cd25d\n\n
To get started, you first need a client. There are SSE clients available in many languages.
Begin by getting a stream. Only one stream is needed
regardless of the number of subscriptions you later create. As explained in the
documentation for getting a stream, the first event, hello, is a special event
because the data field contains your stream ID.
Some operations support the METASYS-SUBSCRIBE header which transforms them
from being a single request/response operations into a streaming subscription.
The value of the header is the stream ID from the data field of the hello
event described above. As an example, refer to the
Get Activities operation for more details about this
technique. This technique does not apply to every operation. See each
operation's description to understand its Streaming capability.
Not all event data is currently exposed by Streaming. Future versions of the API will add further Streaming capabilities.
There are a few behaviors to be aware of if you want your stream to work beyond the lifetime of the access token used to get your stream.
Recall that your access token has a expiration time. To work beyond the lifetime
of that access token, refresh your token just as you
would when using non-Streaming portions of the API. Then call the
keep alive operation, passing your refreshed token in
the Authorization header, to extend your stream for the lifetime of the new
token. Repeat these steps as long as you need the stream to exist. It is
recommended to refresh your token halfway into its life.
The server-sent events standard has a provision for reconnecting a lost
connection. Call the same get a stream operation but
also add the Last-Event-Id header with the id of the last event received.
Most clients handle this for you. Metasys continues to buffer events for at
least thirty seconds after the connection failure is detected, so you can resume
streams that experienced brief outages. If Metasys has cleaned up your buffer or
cannot find that id in the recently sent buffer, you will get a 204 response
per the SSE specification. Because your existing stream is not resumable, your
Last-Event-Id is no longer valid. The recovery path is to start anew by
calling get a stream without the Last-Event-Id and
subscribe again to data of interest.
One critical aspect of reconnect is ensuring that the reconnect request is done
with the current access token. As covered by
get a stream, Streaming lets you specify the token in
either the Authorization header or query string. This flexibility accommodates
a variety of clients. For example, the web browser client, EventSource, does
not provide access to request headers, so you have to use the query string.
For EventSource, this however poses an issue because the reconnect attempt
will be done against the original URL which has a potentially outdated access
token embedded in the query string. For that reason, if you want to use a
JavaScript client, consider using the open source
EventSource component. The Metasys
User Interface (MUI) employs this library to workaround the limitation of the
browser's EventSource . When using it, use the Authorization header instead.
Keep the options object passed to the constructor so you can update the
Authorization property when you refresh your access token.
Assuming:
accessTokenstreamingUrl is the URL for get a streamconst eventSourceOptions = {
headers: {
Authorization = `Bearer ${accessToken}`
}
};
const eventSource = new $window.EventSourcePolyfill(streamingUrl, eventSourceOptions);
Before token expiration:
eventSourceOptions with new token like example beloweventSourceOptions.headers.Authorization = `Bearer ${newToken}`;
SSE clients exist in many languages. Inclusion in this section is not an endorsement; however, if you chose one of these clients, these tips may prove useful for ensuring the current token is used for reconnect.
When using the
3ventic EventSource for C# you will need
to use Reflection to update Uri which is a private field within the
EventSource that contains the location to get a stream
with the access token embedded in the query string.
public static void SetField(Object obj, String fieldName, object value)
{
Type type = obj.GetType();
FieldInfo field = type.GetField(
fieldName,
BindingFlags.NonPublic | BindingFlags.Instance
);
field.SetValue(obj, value);
}
// example usage
Reflector.SetField(eventSource, "Uri", uriWithCurrentToken);
When using the
LaunchDarkly EventSource for C#
you will not call the Reset method to attempt a reconnect. Instead, dispose of
the EventSource and then create a new instance, passing the the LastEventId
from the last message and the URL to get a stream with a
current access token embedded as a query string parameter.
The following are types of events sent by Streaming along with example data
payloads for each:
hello - Indicates Streaming connection was successful.
"b6d184ee-e137-44aa-b9b1-14bc704cd25d"
heartbeat - Indicates Streaming connection is alive.
"2021-02-16T16:21:10.23Z"
Opens or reconnects a Server Sent Event stream which is a prerequisite for subscribing to any dynamic updates
| Last-Event-Id | string Example: b6d184ee-e137-44aa-b9b1-14bc704cd25d:5 Providing the ID of the last event received enables a briefly broken stream to be resumed |
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/stream \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \ --header 'Last-Event-Id: b6d184ee-e137-44aa-b9b1-14bc704cd25d:5'
Keep all streams associated to the user session alive and open without interruption until the new token expiration or closed by the client.
curl --request GET \ --url https:///%7Bhostname%7D/api/v5/stream/keepalive \ --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'